docs: cleanup historical artifacts (~17k lines)#406
Merged
Conversation
Audit pass over docs/ found a lot of accumulated detritus that no code, skill, or agent references. Removing the unreferenced historical artifacts and fixing the broken cross-references that result. Deletions (~17,300 lines) - docs/superpowers/plans/ — wholesale (11 files, ~13k lines). These were post-shipment implementation plans, zero references from any skill/agent/CLAUDE.md. The PR diff is the truth, not the plan checkboxes. - docs/superpowers/specs/ — 8 unreferenced design docs (~2,100 lines): ace-solicitations-phase-design, app-multimedia-coverage-design, skills-audit-findings, mobile-cloud-runner-poc + api-gaps, ace-sweep-atom-contracts + design, work-order-skill-design. Kept the 5 specs that ARE referenced from skills/CLAUDE.md (shallow-deep-qa-split, decisions-log, qa-eval-migration, state-consolidation, focus-group-archetype-redefinition). - docs/generated/playbook.md — 16-day-stale derived artifact (claimed "8-phase orchestration"; pipeline has been 10-phase for weeks). Regenerated by `/ace:docs` when next needed. Broken cross-references fixed - skills/README.md — two refs to deleted 2026-04-01-ace-design.md replaced with pointers to CLAUDE.md + agents/orchestrator-reference.md and (for the dry-run paragraph) absorbed inline. - skills/upload-transcript/SKILL.md — ref to deleted 2026-05-02-ace-run-multi-run-revival-design.md dropped; the sentence stands on its own. - README.md — Documentation section refreshed; broken refs to ace-design.md and ace-web-harness-design.md replaced with pointers to CLAUDE.md, agents/orchestrator-reference.md, the integrations playbook, and the ace-web sibling repo. Followups not in this PR (called out in the analysis but deferred): - SKILL.md ## Change Log compression (every skill carries 5-13 historical entries that bloat its context every time it dispatches). Bigger code change; deserves its own PR. - .claude/pm/runs/ early-April compaction. Light touch; folds into one durable learning when someone gets to it. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Audit pass over
docs/removed ~17,300 lines of unreferenced historical artifacts. Companion to PR #403 (docregen). Findings from the analysis triggered by the user reviewing what's accumulated in the project.Deletions
docs/superpowers/plans/— wholesale (11 files, ~13k lines). Post-shipment implementation plans. Zero references from any skill/agent/CLAUDE.md. PR diffs are the truth, not plan checkboxes.docs/superpowers/specs/— 8 unreferenced (~2,100 lines):ace-solicitations-phase-design,app-multimedia-coverage-design,skills-audit-findings,mobile-cloud-runner-poc,mobile-cloud-runner-api-gaps,ace-sweep-atom-contracts,ace-sweep-design,work-order-skill-design. Kept the 5 that ARE referenced (shallow-deep-qa-split-design,decisions-log-design,qa-eval-migration,state-consolidation,focus-group-archetype-redefinition).docs/generated/playbook.md— 16-day-stale derived artifact (claimed "8-phase orchestration"; pipeline has been 10-phase for weeks)./ace:docsregenerates it when next needed.Broken cross-references fixed
skills/README.md— 2 refs to deleted2026-04-01-ace-design.mdreplaced with pointers toCLAUDE.md+agents/orchestrator-reference.md(and one absorbed inline).skills/upload-transcript/SKILL.md— ref to deleted2026-05-02-ace-run-multi-run-revival-design.mddropped.README.mdDocumentation section — refreshed; broken anchor refs replaced withCLAUDE.md,agents/orchestrator-reference.md, the integrations playbook, and theace-websibling.Stacking note
This branches from
main, not fromdocs/regen-2026-05-22(PR #403). When #403 lands first, the regenerated CLAUDE.md still mentionsdocs/superpowers/plans/in the Layout section — after this PR lands, that becomes a slightly-stale reference (the directory will be empty). Cheap fix on the next regen; not worth conflict-stacking the PRs.Followups NOT in this PR
## Change Logcompression — 83 skills carry 5-13 historical changelog entries that bloat their context every dispatch. Estimated 5K-line saving. Deserves its own PR (real edit churn)..claude/pm/runs/early-April compaction — light touch; folds into one durable learning when someone gets to it.Test plan
clean-installstatus checkskills/,agents/,README.md,CLAUDE.md(already verified locally)🤖 Generated with Claude Code