# Review Architecture Docs

> Audit and update durable architecture guidance after a cross-layer implementation, file move, package boundary change, coverage config change, or SDTE feature. Use when agent needs to reconcile AGENTS.md, package AGENTS.md files, local .agents/skills, older specs, dynamic imports, and test or coverage configuration with the architecture that was actually implemented.

- Skill: `dkolba/review-architecture-docs` (Agent Skill)
- Install (CLI): `npx skillmds@latest add dkolba/review-architecture-docs`
- Raw SKILL.md: https://api.skillmd.com/api/skills/dkolba/review-architecture-docs/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: dkolba (https://skillmd.com/u/dkolba)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/dkolba/review-architecture-docs

---


# Review Architecture Docs

Use this after implementation changes the canonical shape of the codebase, especially when work:

- moves files or public module paths;
- changes layer responsibilities;
- introduces or retires an architectural boundary;
- updates test, coverage, or build configuration;
- completes an SDTE feature whose design should become durable project guidance.

## Workflow

1. **Collect the implemented facts**
   - Read the changed source files and tests, not just specs.
   - Identify new canonical module paths, public functions, layer ownership, test ownership, and config paths.
   - Note any pre-existing dirty worktree changes and do not revert them.

2. **Audit durable guidance**
   - Root `AGENTS.md`.
   - Every `packages/*/AGENTS.md`.
   - Every local `.agents/skills/*/SKILL.md`.
   - Older specs that mention moved files, old boundaries, or retired plans.
   - Config files whose paths mirror source structure, such as coverage includes/excludes, lint boundaries, build entry points, and dynamic imports.

3. **Search for drift**
   - Use `rg` for old path fragments, old function names, and old architectural claims.
   - Search both exact paths and conceptual terms. Example: after render-command work, search `render`, `RenderCommand`, `Canvas`, `RenderStats`, `effects/render`, and old file paths.
   - Treat older specs as historical records unless they are actively misleading future work. Prefer brief corrections over rewriting history.

4. **Patch only durable guidance**
   - Update rules and skills that future agents must follow.
   - Keep wording implementation-shaped: name the real files, functions, and layer boundary.
   - Do not duplicate detailed design docs in skills; keep skills procedural.
   - Avoid broad refactors or unrelated cleanup.

5. **Verify**
   - Run `npm run ok` when repo-wide instructions, skills, package rules, or config changed.
   - If only markdown outside package formatting changed and the repo gate is too costly, run the nearest documented formatter/gate and state the limitation.

## Checklist

- [ ] Root and package AGENTS files match the implemented layer ownership.
- [ ] Relevant local skills describe the current file paths and workflow.
- [ ] Older specs no longer point future work at removed or renamed files.
- [ ] Dynamic imports still resolve after file moves.
- [ ] Coverage, lint, typecheck, and build config paths match the current tree.
- [ ] Tests mentioned by docs actually exist.
- [ ] Verification command was run and reported.

## Output

Summarize:

- files updated;
- stale guidance removed or corrected;
- guidance reviewed but left unchanged;
- verification run;
- any dirty worktree changes that pre-existed or were intentionally left untouched.