alignment_status: review
Documentation Freshness And Cleanup Audit
Review artifact for research/devtool-docs-audit.md. Generated 2026-06-08 for the repository documentation audit requested by the user.
Executive Verdict
Healthy
The skill catalog is structurally healthy. Dependency, cross-pack routing, version, benchmark-coverage, and alignment-stub checks passed.
P1
Public setup docs mix the old symlink/install model with the current managed-copy/init model.
P1
Several live workflow docs still route to the retired executable icp command instead of customer-discovery.
P1
Current reference docs are mixed with old reports, proposals, and phase records that should move to history or be clearly relabeled.
Findings
P1 Setup Docs Teach The Old Install Model
Current install code creates repo-managed directories with .agentic-skills-managed markers for track-latest installs. Several docs still say active installs are symlinks. The fix is to update live setup and troubleshooting docs to use managed-copy language and reserve symlink language for pinned archive installs.
P1 Global Init Helper Path Is Missing At Root
Live docs refer to scripts/init-agentic-skills.sh, but no root script exists. The helper exists only under global/{claude,codex}/init-agentic-skills/scripts/. Either add a root wrapper or update docs to prefer the skill command and bundled helper path.
P1 Live AFPS Docs Still Reference Retired icp Command
README.md, docs/codex-workflow.md, docs/pack-workflow-matrix.md, and docs/skill-routing-map.html still present icp as an executable route. Active source contracts use customer-discovery.
P1 Historical Reports Sit Beside Current Reference Docs
docs/kanban-test-results.md, docs/workflow-refactor-proposal.html, docs/phases/*, root interview logs, and the dated active specs/drift-report.md need archive or regeneration decisions.
P1 Local Hibernated Kanban Residue Misleads Pack Listing
This workspace contains ignored local residue under packs/poketowork-kanban/. A dry run of git clean -ndX packs/poketowork-kanban reported it would remove that directory. The residue caused skill-name install resolution to see a hibernated skill as locally active; the accidental test install was removed.
P2 Script Reference Is Not A Complete Script Index
docs/scripts-reference.md is useful but overclaims. It omits several root scripts and includes the missing root init helper path. Rename it to common scripts or expand it into a complete table.
P2 Active Packs devtool And game Lack PACK.md
Both packs have active mirrored skills and public references, but no pack-local PACK.md. Add pack metadata using docs/skills-reference.md as the source of truth.
P2 Skills Showcase Generated Proof Data Was Stale
The first scripts/validate-skills-showcase-data.sh run regenerated proof-data assets and failed with a stale-data message. After rerunning both showcase generators, final validation passed with Skills Showcase generated data is fresh. The relevant tracked diffs are source fingerprint updates in both proof-data copies.
Evidence Matrix
| Claim | Evidence | Inference | Confidence | Decision Impact |
|---|---|---|---|---|
| Skill catalog is structurally healthy. | skill-deps, skill-pack-routing-audit, skill-versions, alignment dry-run, and bench coverage passed. | Freshness problems are docs surface issues, not broad catalog breakage. | High | Do targeted docs cleanup instead of large skill refactor. |
| Install docs have model drift. | scripts/skill-links.sh copies managed installs; docs still say symlink in quickstart/troubleshooting/scripts reference. | Users will misunderstand drift and refresh semantics. | High | Update setup docs first. |
| Root init helper path is broken. | test -f scripts/init-agentic-skills.sh returned missing; helper exists under bundled skill paths. | Copy-paste commands in docs fail. | High | Add wrapper or update docs. |
| AFPS route docs are stale. | Active contracts use customer-discovery; several docs still show icp. | Users may invoke a retired command or follow old diagrams. | High | Update current docs and archive stale diagrams/proposals. |
| Historical docs are mixed with live docs. | Dated kanban reports, old proposal HTML, old phase docs, and root session artifacts sit in active locations. | Maintainers cannot quickly tell what is current. | Medium | Move to history/archive or relabel. |
| Generated proof data was stale. | Initial validator run changed proof-data fingerprints; final validator run passed after the two generators. | Generated static proof data needed refresh before shipping audit changes. | High | Commit refreshed generated proof-data assets with audit boundary. |
| Local ignored hibernated residue affects pack commands. | git clean -ndX packs/poketowork-kanban would remove ignored residue; pack install by skill name unexpectedly succeeded before removal. | Workspace-local ignored files can reanimate hibernated skill discovery. | High for this workspace, medium for clean repo | Clean ignored residue and harden pack discovery. |
Evidence Coverage Gate
Is the repo evidence sufficient to accept the audit findings as the cleanup basis?
Cleanup Matrix
| Surface | Classification | Action |
|---|---|---|
README.md | Needs update | Fix icp route and active install wording. |
docs/QUICKSTART.md | Needs update | Replace symlink wording with managed-copy wording. |
docs/packs.md | Mostly current | Fix missing root init-helper references. |
docs/skills-reference.md | Mostly current | Keep; use as source for missing pack docs. |
docs/canonical-workflow-report.md | Current | Keep as canonical AFPS route reference. |
docs/skill-next-step-contracts.md | Current | Keep as routing contract reference. |
docs/codex-workflow.md | Needs update | Replace $icp examples. |
docs/pack-workflow-matrix.md | Needs update | Replace default icp route. |
docs/skill-routing-map.html | Needs update or archive | Regenerate or move to history. |
docs/workflow-refactor-proposal.html | Archive candidate | Move under history as old proposal. |
docs/kanban-test-results.md | Archive candidate | Move under history; workflow is hibernated. |
docs/phases/* | Archive/rationalize candidate | Merge with or move under phase-history convention. |
docs/scripts-reference.md | Needs update | Fix root init path and all-script claim. |
docs/troubleshooting.md | Needs update | Fix managed-copy wording and global helper path. |
docs/test-harness.md | Needs update | Prefer pnpm --dir tests ... examples. |
research/devtool-*.md | Historical or needs reconciliation | Reconcile stale installer/symlink facts or mark historical. |
specs/drift-report.md | Needs regenerate or archive | Latest report predates later routing and hibernation work. |
| Root session files | Archive candidate | Move completed session artifacts out of repo root. |
packs/devtool/PACK.md | Missing | Add pack-level docs. |
packs/game/PACK.md | Missing | Add pack-level docs. |
Assumptions And Confidence
| Conclusion | Status | What Could Change It |
|---|---|---|
| Core skill catalog is healthy. | Evidence-backed | A broader full test run may expose unrelated layer failures, but targeted catalog checks passed. |
| Setup model docs are stale. | Evidence-backed | Would change only if install code is intentionally reverted to symlink-first behavior. |
| Historical docs should move to archive. | Evidence-backed with naming-policy assumption | A repo decision to keep historical reports in active root docs would change the action, not the freshness issue. |
| Pack discovery should ignore hibernated residue. | Evidence-backed for this workspace | A clean clone may not reproduce the local residue, but command hardening remains prudent. |
Alternatives Considered
- Do nothing because core skill checks pass. Rejected: live setup and route docs still have copy-paste failures.
- Only update
icproute examples. Rejected: install-model drift and active/historical doc mixing are equally important. - Archive all old research under
research/. Rejected: some research remains valuable as historical evidence, but it needs explicit status or reconciliation before being used as current examples. - Hard-delete local ignored hibernated residue in this audit. Rejected for now: it is a destructive local cleanup, so the report recommends it separately.
Source Coverage Gaps
- No web research was performed; this is a repo-internal audit.
- The audit did not manually read every documentation-like file. It combined inventory counts, targeted scans, sampled live docs, and repo validators.
- The full test suite was not run. The audit used targeted documentation and skill-integrity checks.
- Some archive decisions need owner preference: move old reports to history, or relabel them in place as historical.
Artifact Destination And Proposed File Changes
Canonical report destination: research/devtool-docs-audit.md.
Previous report archived to: docs/history/archive/2026-06-08/040539/research/devtool-docs-audit.md.
Alignment page destination: alignment/devtool-docs-audit-docs-freshness.html.
Prompt history destination: prompts/devtool-docs-audit/skill-prompt-20260608-040022-docs-freshness-cleanup.md.
Task tracking destinations: tasks/roadmap.md and tasks/todo.md.
Generated proof-data assets changed after the final generator run: docs/skills-showcase/assets/github-proof-data.js and apps/skills-showcase/public/assets/github-proof-data.js.
Complete Report Content
The full canonical Markdown report is rendered below for no-context-loss review. Source path: research/devtool-docs-audit.md.
# Devtool Docs Audit - Documentation Freshness And Cleanup (2026-06-08) Scope: current repository documentation for the `agentic-skills` shared skill library, with emphasis on whether live docs still match the current install model, pack model, AFPS routing, generated-data contract, and historical/archive boundaries. Executive verdict: - P0: none. Core skill catalog is structurally healthy. - P1: setup docs mix the old symlink/install model with the current managed-copy/init model. - P1: live workflow docs still route to retired `icp` in several places. - P1: `docs/` mixes current reference material with old reports/proposals that should be archived or relabeled. - P1: ignored local `packs/poketowork-kanban/` residue misleads pack listing and skill-name install resolution. - P2: script reference omits root scripts and points at a missing root init helper. - P2: active `devtool` and `game` packs lack `PACK.md`. - P2: generated Skills Showcase proof data was stale and passed after regeneration. Primary cleanup order: 1. Fix live copy-paste blockers: root init helper path, managed-copy wording, and `icp` route examples. 2. Commit the regenerated Skills Showcase proof-data updates. 3. Archive or relabel historical docs in active-looking locations. 4. Add missing `PACK.md` files for `devtool` and `game`. 5. Regenerate or archive `specs/drift-report.md`. 6. Harden `scripts/pack.sh` against ignored hibernated-pack residue. Verification: - `scripts/skill-deps.sh --broken`: passed. - `scripts/skill-pack-routing-audit.sh`: passed. - `scripts/skill-versions.sh --missing`: passed, all 405 skills have versions. - `node scripts/upgrade-alignment-page.mjs --dry-run`: passed with no drift. - `pnpm --dir tests bench:coverage`: passed, 185 skills. - Initial `scripts/validate-skills-showcase-data.sh`: failed after regenerating stale proof-data fingerprints. - Final `scripts/validate-skills-showcase-data.sh`: passed after the two showcase generators. Recommended next skill: `$exec` to implement the first cleanup slice after approval.
Approval Gates
Recommended Path Gate
Which cleanup path should be used after this audit?
Proposed File Changes Gate
Do you approve the audit artifact destinations and generated-data refresh boundary?
Bottom Compile Section
Use feedback YAML for revisions before final approval. Use compiled answers when all required gates are answered.