Devtool Docs Audit — agentic-skills
confirmed 2026-06-05 Third-pass documentation audit
Third-pass audit of developer-facing documentation for the agentic-skills shared skill library. All P1 and P2 findings have been implemented. This page is current for the completed alignment cycle and remains amendable when later changes extend the conclusions.
Confirmation Record
- alignment_status: confirmed
- confirmed_date: 2026-06-05
- confirmed_artifacts:
research/devtool-docs-audit-2026-06-04.md— canonical audit report (dated, preserves prior)docs/QUICKSTART.md— new quickstart guide with AFPS workflow leaddocs/troubleshooting.md— new symptom-led troubleshooting pagedocs/scripts-reference.md— new compact command indexREADME.md— added Prerequisites section, Troubleshooting section, quickstart linkdocs/skill-anatomy.md— added minimal SKILL.md template and "First Time?" calloutdocs/packs.md— added Team Setup Checklist section- 6 research files — added dated reconciliation notes for stale
install.shreferences
- approval_source: User-provided compiled YAML with all 7 gates answered
- prior_review_archived:
docs/history/archive/2026-06-05/120000/alignment/devtool-docs-audit-agentic-skills-review.html
This page is finished and current for the completed alignment cycle. It remains amendable when later research changes or extends the conclusions.
Table of Contents
Executive Verdict
P0: none. No critical documentation blockers. An experienced shell user can install and use the tool from existing docs.
P1 (3 findings) — all resolved:
- First-success route — created
docs/QUICKSTART.mdwith AFPS workflow lead and linked from README - Troubleshooting — created
docs/troubleshooting.mdand added summary table to README - Prerequisites — added Prerequisites section to README before Initialization
P2 (4 findings) — all resolved:
- Added minimal SKILL.md template and "First Time?" callout to
docs/skill-anatomy.md - Created compact command index at
docs/scripts-reference.md - Added Team Setup Checklist to
docs/packs.md - Added dated reconciliation notes to 6 research files with stale
install.shreferences
P3 (2 findings) — deferred: no visual proof artifacts, static benchmark trends
Findings & Resolutions
P1
Resolved
First-Success Route
README explained the pieces (init.sh, pack install, CLI reload) but did not package a guided path from clone to visible working skill.
Evidence: No quickstart section existed. Workflow split across 3+ docs. Prior audit recommended this; not yet added.
Resolution: Created
docs/QUICKSTART.md with prerequisites, 6-step guided path, AFPS workflow lead-in, and "What's Next" pointers. Linked from README Prerequisites section. User requested separate doc (not inline README section) and AFPS skills workflow lead.
P1
Resolved
Troubleshooting Fragmented
Recovery information existed across 5+ docs but no symptom-led support path existed.
Evidence: No
docs/troubleshooting.md. Recovery facts scattered across README, packs.md, operating-modes.md, skills-reference.md.
Resolution: Created
docs/troubleshooting.md with quick-reference symptom table (10 rows) and detailed recovery procedures for skill visibility, drift, jq errors, lock contention, global drift, Windows/WSL, and validation. Added summary troubleshooting table to README per user request.
P1
Resolved
Prerequisites Undocumented
Hard system dependencies (jq, Claude Code/Codex, bash) were never listed upfront.
Evidence: jq required for pack operations (pack.sh line 49 error). pnpm required for tests. No Prerequisites section in README.
Resolution: Added Prerequisites section to README.md before Initialization, listing bash, jq (with install commands), Claude Code/Codex, and pnpm (optional).
P2
Resolved
No Skill Authoring Template
First-time skill authors had no copyable starting point despite thorough reference docs.
Resolution: Added "First Time?" section to
docs/skill-anatomy.md with pointers to /skill-interview, /create-agentic-skill, and /targeted-skill-builder. Added a minimal SKILL.md template with required fields annotated.
P2
Resolved
Script Reference Scattered
Commands spread across 5+ docs with no compact index.
Resolution: Created
docs/scripts-reference.md with grouped tables: Install & Global, Project Packs, Mode & Handoff, Skill Hygiene, Global Skill Management, Testing & Benchmarks, Showcase & Data Generation, Alignment Page Management. Linked from README Troubleshooting section.
P2
Resolved
Team Adoption Checklist Absent
Team use mechanics documented but no actionable checklist existed.
Resolution: Added "Team Setup Checklist" section to
docs/packs.md with 7 steps: checkout path, init, commit policy, generated roots, refresh after pull, CLI restart, and shipping workflow agreement.
P2
Resolved
Stale install.sh References
Six research files referenced install.sh (renamed to init.sh).
Resolution: Added dated reconciliation blockquote to each file noting the rename. Files treated as historical snapshots with dated caveat rather than rewriting all references (which would break line-number citations).
Affected: devtool-adoption.md, devtool-dx-journey.md, devtool-monetization.md, devtool-user-map.md, devtool-integration-map.md, devtool-positioning.md
Affected: devtool-adoption.md, devtool-dx-journey.md, devtool-monetization.md, devtool-user-map.md, devtool-integration-map.md, devtool-positioning.md
P3
No Visual Proof Artifacts (deferred)
29 HTML alignment pages exist but no screenshots/recordings. Low priority — HTML pages serve power users and the tool is CLI-driven.
P3
Benchmark Trends Static (deferred)
Benchmark matrix is current but point-in-time only. No time-series analysis. Sufficient for current needs.
Progress Since Prior Audit (2026-06-02)
| Prior Backlog Item | Status | Resolution |
|---|---|---|
| 1. Add README first-success and proof sections | Done | Created docs/QUICKSTART.md, linked from README |
| 2. Add docs/troubleshooting.md | Done | Created with symptom table + detailed procedures |
| 3. Add script reference | Done | Created docs/scripts-reference.md |
| 4. Add team adoption checklist | Done | Added to docs/packs.md |
| 5. Reconcile stale install.sh references | Done | Added dated reconciliation notes to 6 files |
All five prior items resolved. Four new findings added: prerequisites (P1, resolved), skill template (P2, resolved), visual proof (P3, deferred), benchmark trends (P3, deferred).
Evidence Matrix
| Claim | Evidence | Confidence | Resolution |
|---|---|---|---|
| No P0 blocker | README covers init, pack install, restart, mode | High | No emergency rewrite needed |
| First-success implicit | No quickstart section; workflow split across 3+ docs | High | Created docs/QUICKSTART.md |
| Troubleshooting fragmented | Recovery info across 5 docs; no symptom table | High | Created docs/troubleshooting.md + README section |
| Prerequisites undocumented | jq hard-required; not in README | High | Added Prerequisites to README |
| No skill template | Anatomy docs thorough; no skeleton | Medium-high | Added template to skill-anatomy.md |
| Script reference scattered | Commands in 5+ docs | Medium-high | Created docs/scripts-reference.md |
| Team checklist absent | Mechanics documented; checklist missing | Medium-high | Added checklist to docs/packs.md |
| Stale installer refs | install.sh absent; research uses it | High | Added dated reconciliation notes |
Assumptions & Confidence
- High confidence: All P1 and P2 items have been addressed with concrete documentation changes
- High confidence: jq is now listed as a prerequisite upfront
- Medium-high confidence: The skill template and script reference will meaningfully reduce onboarding friction
- Medium confidence: Team adoption checklist may need revision as team usage patterns emerge
What Would Change These Conclusions
- If user feedback reveals the quickstart flow is still unclear, the QUICKSTART.md may need revision
- If new scripts are added, docs/scripts-reference.md should be updated
- If team adoption surfaces new friction points, the packs.md checklist should be extended
Approval Record
Gate Decisions (from user-compiled YAML)
First-Success Route (proposed file changes)
Answer:
Notes: "We can also lead with how to get started with the AFPS skills workflow"
Answer:
separate-doc — Create separate docs/QUICKSTART.mdNotes: "We can also lead with how to get started with the AFPS skills workflow"
Troubleshooting Format (proposed file changes)
Answer:
Notes: "also add a troubleshooting section to readme.md"
Answer:
dedicated-page — Create dedicated docs/troubleshooting.mdNotes: "also add a troubleshooting section to readme.md"
Prerequisites (proposed file changes)
Answer:
Answer:
add-section — Add Prerequisites section to README.md
Evidence Coverage (evidence coverage)
Answer:
Answer:
sufficient — Evidence is sufficient
Scope & Non-Goals (scope/non-goals)
Answer:
Answer:
scope-correct — Scope is correct as-is
Artifact Destination (artifact destination)
Answer:
Answer:
research-dated — research/devtool-docs-audit-2026-06-04.md (dated, preserves prior)
Post-Approval Route (post-approval route)
Answer:
Answer:
implement-all — Implement all P1+P2 fixes