doc-review

Name: doc-review
Author: opendatahub-io

36stars74forks

How to install doc-review?

opendatahub-io/ai-helpers/doc-review

$npx -y skills add opendatahub-io/ai-helpers --skill doc-review

Installs into the current project.

Summary

Use this skill to perform adversarial review of AsciiDoc documentation against context sources. Checks factual accuracy, completeness, consistency, and hallucination. Produces workspace/review-findings.json.

Files · 1

View on GitHub

SKILL.md

1	# doc-review
2
3	Perform adversarial comparison of documentation content against context sources to detect inaccuracies, omissions, and hallucinations.
4
5	## Prerequisites
6
7	- AsciiDoc files to review (specified in arguments)
8	- `workspace/context-package.json` should exist for cross-reference checking
9
10	## Parse arguments
11
12	`$ARGUMENTS` contains:
13	1. Target: file path, directory, or glob pattern for AsciiDoc files to review
14	2. --context (optional): path to context package (defaults to `workspace/context-package.json`)
15
16	## Step 1: Discover files
17
18	Resolve the target to a list of `.adoc` files:
19	- Single file: review that file
20	- Directory: glob `*/.adoc`
21	- Glob pattern: expand it
22
23	## Step 2: Load context
24
25	Read `workspace/context-package.json` and extract:
26	- Ticket metadata (summary, description, components)
27	- Context files with content (source code, API specs, architecture docs, existing docs)
28	- Product conventions
29
30	Group context files by type for targeted comparison:
31	- Source code: `.go`, `.py`, `.java` files — authoritative for API behavior
32	- API specs: `_types.go`, `.yaml` CRD files — authoritative for field names and schemas
33	- Architecture docs: `.md` files from architecture repos — authoritative for design
34	- Existing docs: `.adoc` files — reference for style and terminology
35
36	## Step 3: Review each file
37
38	For each AsciiDoc file, read its content and construct a review prompt combining:
39
40	1. Read `${CLAUDE_SKILL_DIR}/prompts/review-content.md` template
41	2. The documentation content being reviewed
42	3. Relevant context files (matched by topic/component)
43	4. Ticket metadata
44
45	Ask the LLM to perform adversarial review:
46
47	- Factual accuracy: Compare every technical claim against source code and API specs
48	- Completeness: Check if important details from the ticket and context are covered
49	- Consistency: Verify terminology matches existing documentation
50	- Hallucination check: Flag any API fields, CLI flags, config options, or behaviors not found in context sources
51
52	## Step 4: Compile findings
53
54	Merge findings from all reviewed files:
55
56	```json
57	{
58	"reviewed_at": "2026-04-14T10:50:00Z",
59	"files_reviewed": 3,
60	"confidence": 0.78,
61	"summary": "Documentation is largely accurate but has 2 technical issues...",
62	"findings": [
63	{
64	"category": "technical_inaccuracy",
65	"severity": "high",
66	"description": "The documented API field 'replicas' should be 'minReplicas'",
67	"file_path": "modules/serving/pages/ref_model-serving-params.adoc",
68	"line_start": 42,
69	"line_end": 42,
70	"context_source": "api/v1alpha1/servingruntime_types.go:87",
71	"suggestion": "Change 'replicas' to 'minReplicas' per the CRD type definition"
72	}
73	],
74	"summary_by_severity": {
75	"high": 1,
76	"medium": 2,
77	"low": 3,
78	"total": 6
79	}
80	}
81	```
82
83	## Step 5: Write findings
84
85	Write `workspace/review-findings.json`.
86
87	## Output
88
89	Primary: `workspace/review-findings.json`
90	Report to caller: confidence score, total findings by severity, files reviewed.
91
92	## Stop conditions
93
94	- Halt: No files found matching target
95	- Warn and continue: Context package missing (review without cross-reference)
96	- Continue: Individual file review fails (record error, continue with others)

People who liked this also viewed

6 picks

Type

doc-review

36stars74forks

View on GitHub

How to install doc-review?

opendatahub-io/ai-helpers/doc-review

$npx -y skills add opendatahub-io/ai-helpers --skill doc-review

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# doc-review
2
3	Perform adversarial comparison of documentation content against context sources to detect inaccuracies, omissions, and hallucinations.
4
5	## Prerequisites
6
7	- AsciiDoc files to review (specified in arguments)
8	- `workspace/context-package.json` should exist for cross-reference checking
9
10	## Parse arguments
11
12	`$ARGUMENTS` contains:
13	1. Target: file path, directory, or glob pattern for AsciiDoc files to review
14	2. --context (optional): path to context package (defaults to `workspace/context-package.json`)
15
16	## Step 1: Discover files
17
18	Resolve the target to a list of `.adoc` files:
19	- Single file: review that file
20	- Directory: glob `*/.adoc`
21	- Glob pattern: expand it
22
23	## Step 2: Load context
24
25	Read `workspace/context-package.json` and extract:
26	- Ticket metadata (summary, description, components)
27	- Context files with content (source code, API specs, architecture docs, existing docs)
28	- Product conventions
29
30	Group context files by type for targeted comparison:
31	- Source code: `.go`, `.py`, `.java` files — authoritative for API behavior
32	- API specs: `_types.go`, `.yaml` CRD files — authoritative for field names and schemas
33	- Architecture docs: `.md` files from architecture repos — authoritative for design
34	- Existing docs: `.adoc` files — reference for style and terminology
35
36	## Step 3: Review each file
37
38	For each AsciiDoc file, read its content and construct a review prompt combining:
39
40	1. Read `${CLAUDE_SKILL_DIR}/prompts/review-content.md` template
41	2. The documentation content being reviewed
42	3. Relevant context files (matched by topic/component)
43	4. Ticket metadata
44
45	Ask the LLM to perform adversarial review:
46
47	- Factual accuracy: Compare every technical claim against source code and API specs
48	- Completeness: Check if important details from the ticket and context are covered
49	- Consistency: Verify terminology matches existing documentation
50	- Hallucination check: Flag any API fields, CLI flags, config options, or behaviors not found in context sources
51
52	## Step 4: Compile findings
53
54	Merge findings from all reviewed files:
55
56	```json
57	{
58	"reviewed_at": "2026-04-14T10:50:00Z",
59	"files_reviewed": 3,
60	"confidence": 0.78,
61	"summary": "Documentation is largely accurate but has 2 technical issues...",
62	"findings": [
63	{
64	"category": "technical_inaccuracy",
65	"severity": "high",
66	"description": "The documented API field 'replicas' should be 'minReplicas'",
67	"file_path": "modules/serving/pages/ref_model-serving-params.adoc",
68	"line_start": 42,
69	"line_end": 42,
70	"context_source": "api/v1alpha1/servingruntime_types.go:87",
71	"suggestion": "Change 'replicas' to 'minReplicas' per the CRD type definition"
72	}
73	],
74	"summary_by_severity": {
75	"high": 1,
76	"medium": 2,
77	"low": 3,
78	"total": 6
79	}
80	}
81	```
82
83	## Step 5: Write findings
84
85	Write `workspace/review-findings.json`.
86
87	## Output
88
89	Primary: `workspace/review-findings.json`
90	Report to caller: confidence score, total findings by severity, files reviewed.
91
92	## Stop conditions
93
94	- Halt: No files found matching target
95	- Warn and continue: Context package missing (review without cross-reference)
96	- Continue: Individual file review fails (record error, continue with others)

People who liked this also viewed

6 picks

Type