audit-docs

Name: audit-docs
Author: gtrabanco

35installs2forks

How to install audit-docs?

gtrabanco/agentic-workflow/audit-docs

$npx -y skills add gtrabanco/agentic-workflow --skill audit-docs

Installs into the current project.

Summary

Audit cross-document coherence: docs ↔ roadmap ↔ code ↔ fix index ↔ issues. Finds drift — features in docs/ not in the roadmap (or vice versa), fix-index entries already merged/closed, broken documentation-map links, dependency cycles, artifacts in the wrong language, naming-conv

Files · 1

View on GitHub

SKILL.md

1	# Audit Docs
2
3	A read-first audit answering "do the docs still match reality?" Produces a
4	findings report; it does not silently rewrite docs.
5
6	## Turn contract — verify before ending the turn
7
8	```
9	✓ The AUDIT DOCS fixed-format report was printed, ending in `Decision: PASS \| FAIL`
10	✓ No doc was rewritten without explicit --fix / user go-ahead
11	✓ The closing `→ Next:` block is printed as the ABSOLUTE last output
12	```
13
14	About to end the turn with any box unchecked? The turn is NOT done — complete
15	the missing box first (weak models drop end-of-document duties; this list is
16	first on purpose).
17
18	## When to use
19
20	- Before a release or milestone, after merging several features/fixes, or
21	whenever the doc set might have drifted from the code and issues.
22
23	## Step 0 — Discover the project (always first)
24
25	Per the agent guide's Workflow conventions + documentation map, then read
26	what THIS skill needs: the roadmap, the fix index + template, and the feature
27	folder layout — the map tells you which links and invariants to check.
28
29	## Checks
30
31	Run these and collect findings (cite paths/lines/issue numbers each):
32
33	1. Roadmap ↔ feature folders. Every `docs/features/<NN>-<slug>/` is in the
34	roadmap, and every roadmap entry has a folder (or is explicitly "scheduled").
35	2. Feature dependencies. SPEC `Depends on` / `Branch` fields are valid; no
36	dependency cycles; ordering is consistent with the roadmap.
37	3. Fix index hygiene. Every entry maps to an open issue and an unmerged
38	branch; flag entries whose issue is closed or whose PR merged (should have
39	been removed). Flag open fix branches missing from the index.
40	4. Documentation-map links resolve. Every file the map references exists;
41	flag "scheduled, not yet authored" items so they aren't mistaken for drift.
42	5. Broken intra-doc links. Relative links/anchors point at real
43	files/sections.
44	6. Issue references. Acceptance/known-issues lines referencing `#N` aren't
45	pointing at long-closed issues without note.
46	7. Language & naming conventions. Artifacts in the project's docs language
47	(this repo: English); file/dir naming matches conventions (e.g.
48	kebab-case TS files, PascalCase components).
49	8. Invariant tags. If the project uses invariant/decision IDs (e.g.
50	INV-/D-/KI-), spot-check that referenced IDs exist where claimed.
51	9. PR-link integrity on `done` rows. Every roadmap row (and fix-index
52	entry) with status `done` carries a linked PR reference —
53	`done · [#<pr>](<pr-url>)`. For each bare `done`, find its PR in the forge
54	(`gh pr list --state all --head feat/<NN>-<slug>` or by title) and propose
55	the row update; a `done` with no PR found at all is HIGH severity (the unit
56	may never have been closed out).
57
58	Workflow discipline (checks 10–14) — the executor skills enforce these at
59	write time; this audit verifies they actually held. Each check is mechanical:
60	run the command shown, don't infer.
61
62	10. Phase naming. `grep -rnE '\bS[0-9]+\b\|\bStep [0-9]' docs/features/*/{PLAN,TASKS,progress}.md`
63	must return nothing — plans use `P1, P2, …` ("phases") only. Any hit: LOW
64	(rename), plus check the executor argument still resolves.
65	11. Per-phase doc discipline. For every M/L feature `in-progress`/`done`:
66	completed phases are ticked in `TASKS.md`, `progress.md` has one entry per
67	completed phase, and (features planned under the current template) the
68	final phase ends with the literal close-out tasks (open PR + print URL,
69	link roadmap row, push the link commit). A `done` feature with unticked
70	tasks or a phase missing from `progress.md`: HIGH.
71	12. Branch & PR discipline vs the forge. For every `done` unit: its PR
72	exists, targets the default branch, has a non-empty body, and carries
73	`Closes #<n>` when the unit is issue-born (SPEC references an issue).
74	Also scan recent default-branch history (`git log --first-parent`) for
75	feature/fix-scoped changes committed directly without a PR: HIGH

People who liked this also viewed

6 picks

Type

audit-docs

35installs2forks

View on GitHub

How to install audit-docs?

gtrabanco/agentic-workflow/audit-docs

$npx -y skills add gtrabanco/agentic-workflow --skill audit-docs

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Audit Docs
2
3	A read-first audit answering "do the docs still match reality?" Produces a
4	findings report; it does not silently rewrite docs.
5
6	## Turn contract — verify before ending the turn
7
8	```
9	✓ The AUDIT DOCS fixed-format report was printed, ending in `Decision: PASS \| FAIL`
10	✓ No doc was rewritten without explicit --fix / user go-ahead
11	✓ The closing `→ Next:` block is printed as the ABSOLUTE last output
12	```
13
14	About to end the turn with any box unchecked? The turn is NOT done — complete
15	the missing box first (weak models drop end-of-document duties; this list is
16	first on purpose).
17
18	## When to use
19
20	- Before a release or milestone, after merging several features/fixes, or
21	whenever the doc set might have drifted from the code and issues.
22
23	## Step 0 — Discover the project (always first)
24
25	Per the agent guide's Workflow conventions + documentation map, then read
26	what THIS skill needs: the roadmap, the fix index + template, and the feature
27	folder layout — the map tells you which links and invariants to check.
28
29	## Checks
30
31	Run these and collect findings (cite paths/lines/issue numbers each):
32
33	1. Roadmap ↔ feature folders. Every `docs/features/<NN>-<slug>/` is in the
34	roadmap, and every roadmap entry has a folder (or is explicitly "scheduled").
35	2. Feature dependencies. SPEC `Depends on` / `Branch` fields are valid; no
36	dependency cycles; ordering is consistent with the roadmap.
37	3. Fix index hygiene. Every entry maps to an open issue and an unmerged
38	branch; flag entries whose issue is closed or whose PR merged (should have
39	been removed). Flag open fix branches missing from the index.
40	4. Documentation-map links resolve. Every file the map references exists;
41	flag "scheduled, not yet authored" items so they aren't mistaken for drift.
42	5. Broken intra-doc links. Relative links/anchors point at real
43	files/sections.
44	6. Issue references. Acceptance/known-issues lines referencing `#N` aren't
45	pointing at long-closed issues without note.
46	7. Language & naming conventions. Artifacts in the project's docs language
47	(this repo: English); file/dir naming matches conventions (e.g.
48	kebab-case TS files, PascalCase components).
49	8. Invariant tags. If the project uses invariant/decision IDs (e.g.
50	INV-/D-/KI-), spot-check that referenced IDs exist where claimed.
51	9. PR-link integrity on `done` rows. Every roadmap row (and fix-index
52	entry) with status `done` carries a linked PR reference —
53	`done · [#<pr>](<pr-url>)`. For each bare `done`, find its PR in the forge
54	(`gh pr list --state all --head feat/<NN>-<slug>` or by title) and propose
55	the row update; a `done` with no PR found at all is HIGH severity (the unit
56	may never have been closed out).
57
58	Workflow discipline (checks 10–14) — the executor skills enforce these at
59	write time; this audit verifies they actually held. Each check is mechanical:
60	run the command shown, don't infer.
61
62	10. Phase naming. `grep -rnE '\bS[0-9]+\b\|\bStep [0-9]' docs/features/*/{PLAN,TASKS,progress}.md`
63	must return nothing — plans use `P1, P2, …` ("phases") only. Any hit: LOW
64	(rename), plus check the executor argument still resolves.
65	11. Per-phase doc discipline. For every M/L feature `in-progress`/`done`:
66	completed phases are ticked in `TASKS.md`, `progress.md` has one entry per
67	completed phase, and (features planned under the current template) the
68	final phase ends with the literal close-out tasks (open PR + print URL,
69	link roadmap row, push the link commit). A `done` feature with unticked
70	tasks or a phase missing from `progress.md`: HIGH.
71	12. Branch & PR discipline vs the forge. For every `done` unit: its PR
72	exists, targets the default branch, has a non-empty body, and carries
73	`Closes #<n>` when the unit is issue-born (SPEC references an issue).
74	Also scan recent default-branch history (`git log --first-parent`) for
75	feature/fix-scoped changes committed directly without a PR: HIGH

People who liked this also viewed

6 picks

Type