doc-gap

Name: doc-gap
Author: opendatahub-io

36stars74forks

How to install doc-gap?

opendatahub-io/ai-helpers/doc-gap

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

Installs into the current project.

Summary

Use this skill to analyze context sufficiency for documentation generation. Reads workspace/context-package.json and produces workspace/gap-report.json with severity-rated gaps and a proceed/gather-more/stop recommendation.

Files · 1

View on GitHub

SKILL.md

1	# doc-gap
2
3	Assess whether the gathered context is sufficient to produce quality documentation.
4
5	## Prerequisites
6
7	`workspace/context-package.json` must exist (produced by `doc-gather`).
8
9	## Parse arguments
10
11	`$ARGUMENTS` optionally contains a component name to focus the analysis on. If empty, analyze all components found in the context package.
12
13	Input validation:
14	- If a component name is provided, validate it against the component list in `workspace/context-package.json`.
15	- Accept only exact matches against known component names.
16	- If the component name is not found, halt with a clear error and do not run LLM assessment.
17
18	## Step 1: Read context package
19
20	Read `workspace/context-package.json` and extract:
21	- Ticket metadata (summary, components, fix_versions)
22	- List of gathered context files with their source types
23	- Product configuration (docs conventions)
24
25	## Step 2: Deterministic coverage checks
26
27	Perform these checks without LLM judgment:
28
29	1. Component coverage: For each component in the ticket, check if at least one context file from that component's repo exists.
30	2. Documentation existence: Check if existing documentation files are present in the context.
31	3. API reference availability: If the ticket involves API changes, check for CRD type definitions or API spec files.
32	4. Source code presence: Check if implementation source code is included.
33	5. Architecture docs: Check for architecture context files.
34
35	Record each check as a finding with pass/fail status.
36
37	## Step 3: LLM assessment
38
39	Read the gap analysis prompt from `${CLAUDE_SKILL_DIR}/prompts/gap-analysis.md`.
40
41	Construct an LLM prompt combining:
42	- The gap analysis prompt template
43	- Ticket metadata from the context package
44	- Summary of gathered files (file paths, source types, relevance scores)
45	- Content snippets from the highest-scored files (first 500 chars each, up to 20 files), after deterministic secret/PII redaction
46	- Results of deterministic checks from Step 2
47
48	Before prompt assembly, apply deterministic redaction to all snippets:
49	- Detect and mask secrets (API keys, tokens, passwords, private keys, kubeconfig credentials) with consistent placeholders (e.g., `<REDACTED_TOKEN_1>`).
50	- Mask PII fields (emails, phone numbers) unless explicitly required.
51	- Record redaction statistics (number of snippets scanned, items redacted by type) for inclusion in the gap report.
52
53	Ask the LLM to assess:
54	- Is the context sufficient to write accurate docs?
55	- What specific information is missing?
56	- What is the recommendation: proceed, gather-more, or stop?
57
58	## Step 4: Synthesize findings
59
60	Combine deterministic check results with LLM assessment into a unified gap report.
61
62	## Step 5: Write gap report
63
64	Write `workspace/gap-report.json` with this structure:
65
66	```json
67	{
68	"recommendation": "proceed",
69	"confidence": 0.82,
70	"summary": "Context is sufficient for basic documentation...",
71	"deterministic_checks": [
72	{
73	"check": "component_coverage",
74	"status": "pass",
75	"details": "Found context for 2/2 ticket components"
76	}
77	],
78	"gaps": [
79	{
80	"severity": "medium",
81	"category": "examples",
82	"description": "No sample YAML configurations found",
83	"impact": "Documentation will lack concrete examples",
84	"suggestion": "Check component repo for example/ directory"
85	}
86	],
87	"existing_coverage": [
88	{
89	"topic": "Model serving overview",
90	"source": "modules/serving/pages/con_model-serving.adoc",
91	"quality": "sufficient"
92	}
93	],
94	"analyzed_at": "2026-04-14T10:35:00Z"
95	}
96	```
97
98	Schema requirements:
99	- Required keys: `recommendation`, `confidence`, `summary`, `deterministic_checks`, `gaps`, `existing_coverage`, `analyzed_at`.
100	- `recommendation` MUST be one of: `proceed`, `gather-more`, `stop`.
101	- `confidence` MUST be a float in [0.0, 1.0].
102	- If schema validation fails, halt and return an error instead of writing a partial report.
103
104	## Output
105
106	Primary: `workspace/gap-report.json`
107	Report to caller: recommendation, confidence score, number of gaps by severity.
108
109	## Gotchas
110
111	- The `workspace/context-package.json` file must already exist (produced by `doc-gather`) — this skill will not create it.
112	- Component names must exactly match entries in the context package; partial or fuzzy matches are rejected.
113	- Snippets are redacted for secrets and PII before LLM assessment, so redaction artifacts in the gap report are expected, not errors.

People who liked this also viewed

6 picks

Type

doc-gap

36stars74forks

View on GitHub

How to install doc-gap?

opendatahub-io/ai-helpers/doc-gap

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

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# doc-gap
2
3	Assess whether the gathered context is sufficient to produce quality documentation.
4
5	## Prerequisites
6
7	`workspace/context-package.json` must exist (produced by `doc-gather`).
8
9	## Parse arguments
10
11	`$ARGUMENTS` optionally contains a component name to focus the analysis on. If empty, analyze all components found in the context package.
12
13	Input validation:
14	- If a component name is provided, validate it against the component list in `workspace/context-package.json`.
15	- Accept only exact matches against known component names.
16	- If the component name is not found, halt with a clear error and do not run LLM assessment.
17
18	## Step 1: Read context package
19
20	Read `workspace/context-package.json` and extract:
21	- Ticket metadata (summary, components, fix_versions)
22	- List of gathered context files with their source types
23	- Product configuration (docs conventions)
24
25	## Step 2: Deterministic coverage checks
26
27	Perform these checks without LLM judgment:
28
29	1. Component coverage: For each component in the ticket, check if at least one context file from that component's repo exists.
30	2. Documentation existence: Check if existing documentation files are present in the context.
31	3. API reference availability: If the ticket involves API changes, check for CRD type definitions or API spec files.
32	4. Source code presence: Check if implementation source code is included.
33	5. Architecture docs: Check for architecture context files.
34
35	Record each check as a finding with pass/fail status.
36
37	## Step 3: LLM assessment
38
39	Read the gap analysis prompt from `${CLAUDE_SKILL_DIR}/prompts/gap-analysis.md`.
40
41	Construct an LLM prompt combining:
42	- The gap analysis prompt template
43	- Ticket metadata from the context package
44	- Summary of gathered files (file paths, source types, relevance scores)
45	- Content snippets from the highest-scored files (first 500 chars each, up to 20 files), after deterministic secret/PII redaction
46	- Results of deterministic checks from Step 2
47
48	Before prompt assembly, apply deterministic redaction to all snippets:
49	- Detect and mask secrets (API keys, tokens, passwords, private keys, kubeconfig credentials) with consistent placeholders (e.g., `<REDACTED_TOKEN_1>`).
50	- Mask PII fields (emails, phone numbers) unless explicitly required.
51	- Record redaction statistics (number of snippets scanned, items redacted by type) for inclusion in the gap report.
52
53	Ask the LLM to assess:
54	- Is the context sufficient to write accurate docs?
55	- What specific information is missing?
56	- What is the recommendation: proceed, gather-more, or stop?
57
58	## Step 4: Synthesize findings
59
60	Combine deterministic check results with LLM assessment into a unified gap report.
61
62	## Step 5: Write gap report
63
64	Write `workspace/gap-report.json` with this structure:
65
66	```json
67	{
68	"recommendation": "proceed",
69	"confidence": 0.82,
70	"summary": "Context is sufficient for basic documentation...",
71	"deterministic_checks": [
72	{
73	"check": "component_coverage",
74	"status": "pass",
75	"details": "Found context for 2/2 ticket components"
76	}
77	],
78	"gaps": [
79	{
80	"severity": "medium",
81	"category": "examples",
82	"description": "No sample YAML configurations found",
83	"impact": "Documentation will lack concrete examples",
84	"suggestion": "Check component repo for example/ directory"
85	}
86	],
87	"existing_coverage": [
88	{
89	"topic": "Model serving overview",
90	"source": "modules/serving/pages/con_model-serving.adoc",
91	"quality": "sufficient"
92	}
93	],
94	"analyzed_at": "2026-04-14T10:35:00Z"
95	}
96	```
97
98	Schema requirements:
99	- Required keys: `recommendation`, `confidence`, `summary`, `deterministic_checks`, `gaps`, `existing_coverage`, `analyzed_at`.
100	- `recommendation` MUST be one of: `proceed`, `gather-more`, `stop`.
101	- `confidence` MUST be a float in [0.0, 1.0].
102	- If schema validation fails, halt and return an error instead of writing a partial report.
103
104	## Output
105
106	Primary: `workspace/gap-report.json`
107	Report to caller: recommendation, confidence score, number of gaps by severity.
108
109	## Gotchas
110
111	- The `workspace/context-package.json` file must already exist (produced by `doc-gather`) — this skill will not create it.
112	- Component names must exactly match entries in the context package; partial or fuzzy matches are rejected.
113	- Snippets are redacted for secrets and PII before LLM assessment, so redaction artifacts in the gap report are expected, not errors.

People who liked this also viewed

6 picks

Type