paulund/ops-architecture-review

Core Workflow

1. Explore

Read every file in docs/adr/ first. ADRs encode accepted design decisions — the patterns documented there (data fetching layer, service interfaces, configuration-driven dispatch, etc.) are the baseline you measure friction against. Any candidate that contradicts an ADR must be flagged as such and linked to the ADR; don't silently re-litigate the decision.

Read CONTEXT.md / CONTEXT-MAP.md if present for domain vocabulary. Don't flag the absence of these files.

Walk the codebase and note friction:

• Where understanding one concept requires bouncing between many small modules
• Where modules are shallow (interface nearly as complex as implementation)
• Where pure functions were extracted for testability but real bugs hide in how they're called (no locality)
• Where tightly-coupled modules leak across their seams
• Which parts are untested or hard to test through their current interface

Apply the deletion test: would deleting the suspect module concentrate complexity (keep) or move it (remove)?

2. Ship candidates as issues

Search GitHub issues for existing reports on the identified friction to avoid duplicates. Present a numbered list of deepening opportunities, then create a GitHub issue for every new candidate.

Issue title — Deepen <module-name>: <one-line outcome>

Issue body:

> *This was generated by AI during triage.*

## Context
<friction this refactor relieves>

> **Recommendation:** Strong | Worth exploring | Speculative — <one-line why>

## Files
- path/to/module/a
- path/to/module/b

## Current shape (shallow)
<deletion test analysis>

## Target shape (deep)
<new interface surface, what stays inside, what the seam looks like>

## Dependency category
TBD — to be filled during grilling loop.

## Seam & adapters
TBD — to be filled during grilling loop.

## Testing strategy
TBD — to be filled during grilling loop.

## Out of scope
TBD — to be filled during grilling loop.

## Acceptance criteria
- [ ] Deepened module exists at <path>
- [ ] Old shallow modules deleted (or thin compatibility shim + follow-up)
- [ ] New tests at deepened interface pass; old tests deleted
- [ ] No callers import old internal modules

Labels (exactly one per category): | Label | When | |---|---| | chore (category) | Always | | planned (state) | Always | | afk (execution) | Default. Use hitl when target shape or AC are genuinely undecided. |

ADR conflicts: If a candidate contradicts an existing ADR, only surface it when friction warrants reopening. Mark it clearly and link the ADR.

When CONTEXT.md is missing domain terms used in issue titles/bodies, add a ## Domain vocabulary notes section below Acceptance criteria.

After creating all issues, print a one-line top recommendation: Start with <issue-url> — <one-line reason>.

3. Grilling loop (user-initiated)

When the user picks a candidate, load references/deepening.md and walk the design tree:

1. Classify dependencies (in-process, local-substitutable, remote-but-owned, true-external)
2. Shape the deepened module — what the interface exposes, what stays inside
3. Decide testing strategy — replace old tests, don't layer
4. Apply seam discipline — port only if 2+ adapters justified
5. Update CONTEXT.md with new/refined domain terms

If the user rejects with a load-bearing architectural reason, post a draft ADR header and ask: "Want me to record this as an ADR?" Close with wontfix.

After grilling, update the issue body with resolved sections. Flip hitl → afk if applicable.

Reference Guide

| File | When to load | |------|-------------| | references/architecture-rules.md | Before step 1 (Explore) and before step 2 (Ship candidates) | | references/language.md | When writing proposals, issue bodies, or documentation | | references/deepening.md | When user initiates step 3 (Grilling loop) |

Constraints

MUST DO

• Use vocabulary from references/language.md exactly. Treat drift as a bug.
• Read every file in docs/adr/ before exploring. ADRs are the baseline; candidates that contradict them must be flagged and linked, not silently re-litigated.
• Read CONTEXT.md / CONTEXT-MAP.md if present for domain vocabulary.
• Apply the deletion test before flagging any module as shallow.
• Check for existing GitHub issues before creating a new one for a candidate.
• Label each issue with exactly one category (chore), one state (planned), one execution (afk/hitl).
• Open every issue body with the AI disclaimer line.
• Every deepening candidate must pass at least one "keep" rule from references/architecture-rules.md.
• In step 3, classify dependencies before proposing a seam.

MUST NOT DO

• Propose interface signatures or code in step 2.
• Suggest creating CONTEXT.md or ADRs upfront.
• Re-litigate ADR decisions unless friction genuinely warrants reopening.
• Substitute glossary terms from references/language.md.
• Introduce a port with only one adapter.
• Layer tests on top of existing tests — replace them.
• Use needs-triage or needs-info on issues from this workflow.
• Bundle multiple candidates into a single issue.