fix: Wave 2 post-merge cleanup — knowledge persistence & command consistency#143
Closed
fix: Wave 2 post-merge cleanup — knowledge persistence & command consistency#143
Conversation
added 6 commits
March 14, 2026 18:58
Add structured knowledge extraction and injection so agents learn from past architectural decisions and known pitfalls across sessions. - Create `.memory/knowledge/decisions.md` (ADR-NNN) and `pitfalls.md` (PF-NNN) - Inject TL;DR headers at session start (~30-50 tokens) - Coder reads decisions before implementation, Reviewer checks pitfalls - /implement records ADRs, /code-review + /debug + /resolve record pitfalls - Both base and Teams command variants updated - createMemoryDir() now creates knowledge/ subdirectory - 8 new tests (246 total), all passing
Batch 1 — Mechanical fixes: - Fix duplicate step 5→6 in 4 explorer prompts (implement-teams.md) - Fix fractional 2.5→3 renumbering in 4 reviewer prompts (code-review-teams.md) - Fix fractional 1.5→2 renumbering in reviewer.md responsibilities - Update stale counts: 24→31 skills, 8→17 plugins (file-organization.md) - Add missing ambient-prompt.sh to hooks listing (file-organization.md) Batch 2 — DRY extraction via knowledge-persistence skill: - Create shared/skills/knowledge-persistence/SKILL.md with canonical procedure (ADR/PF formats, lock protocol, capacity cap, dedup, TL;DR update) - Replace 8 inline extraction procedures with skill references in implement, code-review, debug, resolve (base + teams variants) - Register skill in 4 plugin manifests (plugin.json + plugins.ts) Batch 3 — Hook improvements: - Collapse head+sed+grep into single sed -n for TL;DR extraction - Guard section joins to prevent leading newlines when Section 1 skipped Batch 4 — Quick fixes: - Add TL;DR-only rationale comment to skimmer.md step 6 - Log createMemoryDir errors in verbose mode instead of silent catch - Add 3 hook integration tests (TL;DR injection, no leading newlines, no knowledge section when files absent) Issues dismissed: #9 (TL;DR sanitization — trust model), #10 (integrity verification — instruction-enforced), #17 (mkdir failure test — low value), #18 (phase ordering cosmetic), #19 (intentional scope exclusion)
…eMemoryDir failure test - /specify: Add Phase 2.5 to read decisions.md + pitfalls.md before exploration. Constraints and Failure Modes explorers now receive prior decisions and known pitfalls as context. - /self-review: Phase 0 reads knowledge files. Simplifier and Scrutinizer receive KNOWLEDGE_CONTEXT to check for reintroduced pitfall patterns and verify architectural consistency. - Add createMemoryDir failure test (file blocking mkdir path). Resolves review issues #17 and #19 from PR #140.
The base specify.md got Phase 2.5 (knowledge read) but the teams variant was missed. Both now read decisions.md + pitfalls.md before exploration.
…mmands Eliminates all Phase X.5 numbering introduced by the knowledge-recording phases, replacing with sequential integers and shifting subsequent phases. Files: specify, implement, code-review, debug, resolve (base + teams variants)
…sing - Remove redundant "When This Skill Activates" section from SKILL.md - Add references/examples.md with full ADR and pitfall entry examples - Expand SKILL.md with File Locations, Loading, Extended References sections - Fix description to follow "This skill should be used when..." convention - Add knowledge-persistence to skills-architecture.md reference table - Remove "(if available)" from phase titles in debug, specify, self-review - Remove "if they exist" qualifier from knowledge loading body text - Fix CLAUDE.md stale skill count (31 → 32) Addresses H1, H5, M5, M8 (partial) from issue #142.
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
Post-merge cleanup for the Wave 2 project knowledge system (#99). Addresses consistency audit findings from #142 and code review findings from #140.
knowledge-persistenceskill with full extraction procedure, lock protocol, loading instructions, and examples/debug,/specify,/self-reviewcommands/code-reviewand/resolvecommandscreateMemoryDirfailure test for missing directory edge caseFiles Changed (28 files, +814/-227)
New files (2):
knowledge-persistence/SKILL.md,knowledge-persistence/references/examples.mdCommands (12): All 6 command pairs updated with knowledge phases + sequential numbering
Agents (3): coder, reviewer, skimmer — knowledge context references
Plugins (4): plugin.json manifest updates for knowledge-persistence skill
Tests (1): +230 lines of memory/migration tests
Docs (4): CLAUDE.md, skills-architecture, file-organization, docs-framework
Test plan
npm run buildpasses (32 skills, 17 plugins)npm testpasses (250 tests, 13 test files)/debugloads pitfalls.md before hypothesis generation/specifypasses knowledge context to explore agents