Repository Documentation Alignment Audit

Findings-first review of active documentation consistency across install model, helper paths, workflow routes, npm publication status, Skills Showcase counts, and alignment-page currentness.

alignment_status: reviewGenerated 2026-06-10

skilldevtool-docs-audit

reportresearch/devtool-docs-audit.md

artifactalignment/devtool-docs-audit-documentation-alignment.html

Executive Verdict

P0None found.

Structural documentation gates passed before this page was added: active alignment pages audited cleanly and generated alignment bundles were exact.

P1Setup model drift.

Public setup docs still describe active installs as symlinks, while current code installs active skills as managed copies and reserves symlinks for pinned archives.

P1Retired route drift.

Current docs and indexed alignment pages still route to icp, even though active contracts use customer-discovery.

P1Missing helper path.

scripts/init-agentic-skills.sh is documented, but no root script exists at that path.

P1Stale npm strategy page.

The old npm distribution page remains indexed like current guidance and contains stale agentic-skills package examples.

P2Freshness drift.

Some npm wording still says "after publication" or "release candidate"; Skills Showcase count docs still use old 157/156-count language.

Findings

P1 Setup Docs Mix Symlink And Managed-Copy Models

Current code installs active skills as managed directories and writes .agentic-skills-managed metadata. Pinned archive installs are the symlink case. Public docs still say active global setup symlinks skills.

scripts/skill-links.sh:119-156 copies active skill files and skips archive/.
scripts/skill-links.sh:123-125 uses symlinks for archive sources.
init.sh:146-150 installs active global skills through sync_skill_install.
docs/QUICKSTART.md:25, docs/troubleshooting.md:18, docs/troubleshooting.md:73, and docs/scripts-reference.md:9-10 still use symlink/re-symlink wording.

Recommended cleanup: use "repo-managed copies/directories" for active installs, and reserve "symlink" for pinned archive installs.

P1 Documented Root Init Helper Path Is Missing

Docs recommend scripts/init-agentic-skills.sh, but the root file is absent. The helper exists only under the mirrored init-agentic-skills skill directories.

test -f scripts/init-agentic-skills.sh exits 1.
Existing helper paths: global/claude/init-agentic-skills/scripts/init-agentic-skills.sh and global/codex/init-agentic-skills/scripts/init-agentic-skills.sh.
Current docs reference the missing root path in docs/scripts-reference.md:55-59, docs/troubleshooting.md:72, docs/packs.md:266-268, and docs/operating-modes.md:45.

Recommended cleanup: add a root wrapper or update user-facing docs to prefer /init-agentic-skills and $init-agentic-skills.

P1 Retired `icp` Executable Still Appears In Current Guidance

Active routing has moved to customer-discovery, but several current docs still say icp or /icp.

docs/skill-next-step-contracts.md:75 routes concept-validation proceed states to customer-discovery.
README.md:236 lists business-discovery: icp.
docs/codex-workflow.md:285 and :311 include $icp.
docs/pack-workflow-matrix.md:47 starts the default route with icp.
alignment/canonical-workflow-report.html:320 and :487 still include $icp / business-discovery: icp, and the page is indexed.
research/skills-showcase/idea-brief.md:117, specs/skills-showcase/user-flow-deck-creation.md:14, and alignment/user-flow-map-deck-creation.html:619 still route through /icp.

Recommended cleanup: replace executable routes with customer-discovery while preserving enterprise-icp and research/icp.md where they are intentional names.

P1 Old npm Strategy Page Is Still Presented Like Current Guidance

The current package walkthrough explicitly says the old npm distribution alignment page is historical strategy context, but the old page remains indexed as a normal product-design page and still contains stale package examples.

alignment/skillpacks-npm-package-walkthrough.html:220-226 says it is the current reference and the old page is historical.
alignment/index.html:57-60 indexes Multi-Surface npm Distribution Strategy without a historical label.
alignment/idea-scope-brief-npm-distribution.html:230-251 uses npx agentic-skills and npm install -g agentic-skills.
alignment/idea-scope-brief-npm-distribution.html:585-618 uses npx agentic-skills install-deck, @agentic-skills/*, and agentic-skills install --deck.

Recommended cleanup: add a prominent superseded warning and historical index text, or archive the old page.

P2 npm Publication Docs Still Use Future/Release-Candidate Wording

docs/skillpacks-npm-distribution.md:21-26 says skillpacks@0.1.0 is published publicly, but several public docs still read as pre-publication or release-candidate guidance.

README.md:45 and :105 say npm usage is after publication.
docs/QUICKSTART.md:17, :29, :50, and :83 use before/after-publication language.
docs/decks.md:18 says "After the first public npm package is published"; docs/decks.md:29 says "current release candidate".
docs/skillpacks-npm-distribution.md:372 still calls the shell-backed deck path "this release candidate".

Recommended cleanup: switch to "With the published npm package" and "current skillpacks@0.1.0 release".

P2 Skills Showcase Counts Are Stale Or Ambiguous

Generated data now reports a larger mirrored inventory than older planning docs.

apps/skills-showcase/public/assets/skills-data.js:5-7 reports sourceCount: 545, skillCount: 373, and packCount: 41.
A generated-data parse yielded 373 platform entries, 190 unique mirrored skills, 179 unique pack skills, 11 unique global skills, 188 Claude entries, and 185 Codex entries.
tasks/pack-card-hierarchy.md:5-7 still says 157 unique skills across 38 packs.
alignment/skillmap.html:58, :82, and :119 say 41 packs, 156 pack skills, and 11 global skills.
apps/skills-showcase/docs/deck-builder-ux.md:103, research/skills-showcase/idea-brief.md:44, and alignment/idea-scope-brief-skills-showcase.html:234-238 repeat the old 157 count.

Recommended cleanup: define canonical count terms and regenerate or relabel older Skills Showcase docs.

P3 Historical Docs Are Preserved But Not Always Labeled

Historical content can remain, but index cards and headers need to make currentness explicit. The old npm strategy page, alignment/canonical-workflow-report.html, and docs/workflow-refactor-proposal.html are examples where stale content is discoverable outside archive paths.

Current / Needs Update / Archive Matrix

Surface	Classification	Action
`README.md`	Needs update	Replace retired `icp` in business-discovery list; refresh npm publication wording.
`docs/QUICKSTART.md`	Needs update	Replace symlink and future-publication wording.
`docs/troubleshooting.md`	Needs update	Replace re-symlink wording and fix missing init helper path.
`docs/scripts-reference.md`	Needs update	Fix managed-copy wording and missing root init helper path, or add the wrapper.
`docs/packs.md`	Mostly current	Fix root init helper path references.
`docs/operating-modes.md`	Needs update	Fix root init helper path reference.
`docs/decks.md`	Needs update	Replace future npm and release-candidate wording.
`docs/codex-workflow.md`	Needs update	Replace `$icp` examples.
`docs/pack-workflow-matrix.md`	Needs update	Replace default `icp` route.
`docs/skill-next-step-contracts.md`	Current	Keep as routing source of truth.
`alignment/skillpacks-npm-package-walkthrough.html`	Current	Keep as active package usage reference.
`alignment/idea-scope-brief-npm-distribution.html`	Historical or amend	Add superseded warning/index text or archive.
`alignment/canonical-workflow-report.html`	Needs update or label	Contains stale `icp` route but remains indexed.
`alignment/user-flow-map-deck-creation.html`	Needs update	Replace `/icp` handoff.
`tasks/pack-card-hierarchy.md`	Historical or update	Reconcile 157/38 counts against generated data.
`alignment/skillmap.html`	Needs regenerate or source clarification	Reconcile 156 pack skills against generated 179 unique pack skills.

Evidence Matrix

Claim	Evidence	Impact	Confidence
Active installs are managed copies, not symlink-first.	`scripts/skill-links.sh:119-156`, `init.sh:146-150`.	Refresh and drift docs need managed-copy language.	High
Root init helper path is missing.	`test -f scripts/init-agentic-skills.sh` exits `1`; bundled helper scripts exist under `global/{claude,codex}/...`.	Copy-paste commands fail.	High
`icp` executable is retired in active route guidance.	Current source root is `customer-discovery`; active route contract points to `customer-discovery`.	Readers can invoke or spec against a retired command.	High
Old npm strategy page conflicts with current package walkthrough.	Current walkthrough says old page is historical; old page still indexed and contains stale package examples.	Wrong npm package commands are discoverable.	High
Publication wording is stale.	Published status in `docs/skillpacks-npm-distribution.md`; future/RC wording in README, Quickstart, Decks.	Users may think npm is not live.	Medium
Skills Showcase counts are stale or ambiguous.	Generated data parse versus 157/156-count docs.	Implementation and SEO copy can drift.	High

Assumptions And Confidence

Assumption	Confidence	Reason
Archived skill versions and old task manifests should not be counted as current docs unless indexed or referenced by current docs.	High	The repo keeps history intentionally, and active archive directories are out of normal user paths.
`customer-discovery` is the current executable replacement for `icp`.	High	Active source roots and route contracts use `customer-discovery`.
The generated Skills Showcase data is the canonical current inventory source for website counts.	Medium-high	It is generated and used by the app, but the report still recommends defining count terms before changing copy.
The old npm strategy page should remain as historical decision evidence rather than be deleted.	Medium	The current walkthrough calls it historical strategy context; archival versus warning label is a product-doc decision.

Source Gaps

No web research was performed; this is a repo-internal documentation alignment audit.
The audit did not read every historical prompt, conversation, archived skill version, or task manifest.
The audit reports inconsistencies and recommended cleanup; it does not mutate underlying public docs beyond this report and review page.

Review Gates

Gate 1: Remediation Priority

Fix all P1 public-doc issues first. Fix retired route references first. Fix setup/install docs first.

Gate 2: Init Helper Path Strategy

Add a root wrapper script and keep docs simple. Update docs to use skill commands and bundled helper paths.

Gate 3: Historical Page Handling

Label historical pages in place. Archive superseded pages.

Compile Controls

Compile selected gate answers into YAML for the next remediation pass.