| name | architecture-review |
| description | Explore the codebase for architectural friction (shallow modules, coupling, test gaps) and file local markdown issues under docs/issues/. Use when improving codebase shape, before large refactors, or when find-work should surface design-debt issues. |
| disable-model-invocation | true |
Architecture review
Read-only exploration that ends in filed local issues, not code changes in
this session. Deep modules, boundary tests, ports and adapters.
Homelab constraints still apply
(constraints.md). Do not propose changes that
bypass GitOps truth, Gateway API, or 1Password Item CRs.
Deliverable
One or more issues under docs/issues/<slug>.md (kind: architecture in
frontmatter), each with Problem, Acceptance, and Feedback loop.
Filing is its own lap: file-issue →
review-loop →
draft-commit when authorized.
find-work may rank architecture-review briefs when
scouts surface coupling themes or untested seams.
Workflow
- [ ] 1. Orient: AGENTS.md routing, constraints.md, relevant tree
- [ ] 2. Explore (read-only): parent or explore Task — note friction
- [ ] 3. Present numbered candidates (clusters, coupling, test impact)
- [ ] 4. Operator picks candidates (or rank-1 when autonomous lap authorized)
- [ ] 5. For each pick: problem space + interface sketch (chat); no code yet
- [ ] 6. Write issue file(s) from docs/issues/_template.md
- [ ] 7. Hand off file-issue / draft-commit path
What to look for
- Shallow modules: interface nearly as large as implementation
- Bouncing across many files to understand one concept
- Pure helpers extracted only for testability while integration seams stay bare
- Tightly coupled charts/manifests/scripts with no validation boundary
- Untested controller, gateway, restore, or deploy paths
Friction you hit while exploring is the signal.
Issue content (per candidate)
- Problem — modules involved, coupling, integration risk
- Proposed direction — interface sketch, what complexity moves behind a boundary
- Dependency strategy — in-process | local-substitutable | ports/adapters | external mock
- Feedback loop — boundary test, render check, or dogfood step that proves the refactor
- Testing strategy — new checks; shallow tests to delete after
Do not paste a full plan; link a plan later via project-planner if needed.
Subagents
| Step | Agent |
|---|
| Explore | explore Task or parent reads |
| File | parent or file-issue |
| Deep design | project-planner after alignment if the issue spawns a plan |
Do not
- Edit production manifests or app code in this skill (exploration until issues are filed)
- Open GitLab issues unless the operator directs
- File vague "refactor X" without a named feedback loop
- Create a worktree for this skill — exploration is read-only; worktrees belong
to a later implement lap
