Wiki/Forge session context
Resolve vault via KNOWLEDGE_VAULT_ROOT or wiki config --effective --repo <path>. Do not create durable project memory markdown inside the code repo unless the repo itself is the configured vault.
Forge-tracked use: obey the active Forge phase packet, its required skills, artifact owner, and allowed writes.
Standalone use: route durable memory through Wiki under ${KNOWLEDGE_VAULT_ROOT}/projects/<project>/.
Improve Codebase Architecture
Surface architectural friction and propose deepening opportunities: refactors that turn shallow modules into deep ones for testability and AI-navigability.
Glossary
Use these terms exactly in every suggestion. Full definitions in LANGUAGE.md.
- Module, Interface, Implementation, Depth, Seam, Adapter, Leverage, Locality.
- Deletion test: deleting a shallow module removes complexity; deleting a deep module redistributes complexity.
- The interface is the test surface.
- One adapter = hypothetical seam. Two adapters = real seam.
Process
- Read domain language and ADRs first.
- Explore friction: bouncing between modules, shallow interfaces, leaked seams, tangled callers, and tests that cannot reach behavior.
- Present numbered candidates with files, problem, solution, benefits, locality, leverage, and test impact.
- Use CONTEXT.md vocabulary and architecture terms from LANGUAGE.md.
- Do NOT propose interfaces yet. Ask: "Which of these would you like to explore?"
- In the grilling loop, update CONTEXT.md terms and offer ADRs only for load-bearing decisions.
- Side effects happen inline as decisions crystallize.
Zero-tech-debt lens
Optimize for the code that should exist. Search for real callers before preserving compatibility. Delete dead compatibility paths instead of making them better. Verify the intended flow. Replace tests, don't layer them.
Phase: improvement-review
This skill is loaded during the improvement-review phase (via wiki forge improve).
Find architecture friction — shallow modules, leaked seams, tangled callers — and propose numbered candidates. After the user accepts findings, each accepted candidate becomes Forge-tracked follow-up work (a new feature or slice).
Forge integration
Load this skill when the phase packet lists improve-codebase-architecture.
docs/adr/ → projects//adrs/ with projects//decisions.md as the index.
File the review in the wiki before (or instead of) creating an external issue; accepted findings become Forge-tracked follow-up work.
After architecture review completes: return to /forge — run wiki forge next to advance.
1---2name: improve-codebase-architecture3description: Find deepening refactors that improve leverage, locality, and tests. Use when reviewing architecture, seams, modules, or coupling.4---56<skill_context>7 <skill_dir>skills/improve-codebase-architecture</skill_dir>8 <workspace_dir>/Users/tothemoon/Dev/code-forge/knowledge-wiki-system</workspace_dir>910 <path_policy>11 Relative file references in this SKILL.md normally resolve from skill_dir when they exist there.12 Plain workspace commands like git status and bun test usually run in the workspace unless instructed otherwise.13 Use $PI_SKILL_DIR/path for explicit bundled skill files.14 Use $PI_WORKSPACE/path for explicit workspace/project files.15 </path_policy>16</skill_context>1718## Wiki/Forge session context1920Resolve vault via `KNOWLEDGE_VAULT_ROOT` or `wiki config --effective --repo <path>`. Do not create durable project memory markdown inside the code repo unless the repo itself is the configured vault.21Forge-tracked use: obey the active Forge phase packet, its required skills, artifact owner, and allowed writes.22Standalone use: route durable memory through Wiki under `${KNOWLEDGE_VAULT_ROOT}/projects/<project>/`.2324# Improve Codebase Architecture2526Surface architectural friction and propose deepening opportunities: refactors that turn shallow modules into deep ones for testability and AI-navigability.2728## Glossary2930Use these terms exactly in every suggestion. Full definitions in [LANGUAGE.md](LANGUAGE.md).3132- Module, Interface, Implementation, Depth, Seam, Adapter, Leverage, Locality.33- Deletion test: deleting a shallow module removes complexity; deleting a deep module redistributes complexity.34- The interface is the test surface.35- One adapter = hypothetical seam. Two adapters = real seam.3637## Process38391. Read domain language and ADRs first.402. Explore friction: bouncing between modules, shallow interfaces, leaked seams, tangled callers, and tests that cannot reach behavior.413. Present numbered candidates with files, problem, solution, benefits, locality, leverage, and test impact.424. Use CONTEXT.md vocabulary and architecture terms from [LANGUAGE.md](LANGUAGE.md).435. Do NOT propose interfaces yet. Ask: "Which of these would you like to explore?"446. In the grilling loop, update CONTEXT.md terms and offer ADRs only for load-bearing decisions.457. Side effects happen inline as decisions crystallize.4647## Zero-tech-debt lens4849Optimize for the code that should exist. Search for real callers before preserving compatibility. Delete dead compatibility paths instead of making them better. Verify the intended flow. Replace tests, don't layer them.5051## Phase: improvement-review5253This skill is loaded during the **improvement-review** phase (via `wiki forge improve`).5455Find architecture friction — shallow modules, leaked seams, tangled callers — and propose numbered candidates. After the user accepts findings, each accepted candidate becomes Forge-tracked follow-up work (a new feature or slice).5657## Forge integration5859Load this skill when the phase packet lists `improve-codebase-architecture`.60docs/adr/ → projects/<project>/adrs/ with projects/<project>/decisions.md as the index.61File the review in the wiki before (or instead of) creating an external issue; accepted findings become Forge-tracked follow-up work.62**After architecture review completes:** return to `/forge` — run `wiki forge next` to advance.
fasalzein