Autonomous Review Loop

Multi-dimensional code review that loops autonomously until every quality dimension passes. No human interaction during the loop -- humans see only the final result.

Checklist

1. Identify scope -- which files/changes are being reviewed (milestone diff)
2. Run Dimension 1: Optimization -- check, fix if needed, re-check
3. Run Dimension 2: Simplicity -- check, fix if needed, re-check
4. Run Dimension 3: Modularity -- check, fix if needed, re-check
5. Run Dimension 4: Extensibility -- check, fix if needed, re-check
6. Run Dimension 5: Security -- check, fix if needed, re-check
7. Report results -- show evidence for each dimension
8. Update SESSION.md -- record review outcome

Dimension Checklists

1. Optimization

Ask these questions about the changed code:

• Any O(n²) or worse where O(n) is possible?
• Any unnecessary memory allocations (copies where references work)?
• Any redundant I/O (reading same file twice, duplicate API calls)?
• Any computation that could be cached or memoized?
• Standard library used where possible (no custom implementations of solved problems)?

How to check: Read the diff. For each function, trace the hot path. Count loops-inside-loops. Look for repeated operations.

2. Simplicity

• Every line earns its place? (delete anything that can be deleted without changing behavior)
• No dead code? (commented-out code, unused imports, unreachable branches)
• No magic numbers? (every non-obvious literal has a named constant -- exemptions per GATES.md apply)
• DRY? (logic appearing twice → extract to shared function)
• Flat over nested? (>3 levels of nesting → restructure with early returns or extraction)
• Root cause solutions? (no workarounds, no "fix the symptom" patches)
• No over-abstraction? (abstraction is over-engineering if it has only one concrete implementation AND no documented extension plan)

How to check: For each file, try to remove lines. If removing a line doesn't break anything, it shouldn't be there. Search for raw numbers. Search for duplicated patterns.

3. Modularity

• Single responsibility per file/function/class?
• Clean interfaces between modules? (can you describe what a module does in one sentence?)
• Dependencies flow in one direction? (no circular imports)
• Each module testable in isolation?
• File size reasonable? (>200 lines → review for splitting opportunity)
• Can you change internals without breaking consumers?

How to check: For each module, answer: "What does it do?" If the answer has "and", it's doing too much. Check imports -- draw the dependency graph mentally.

4. Extensibility

• Can new features be added without modifying existing code? (open/closed)
• Configuration over hardcoding where appropriate?
• Plugin/extension points where the design calls for them?
• But YAGNI: no speculative extension points "just in case"

How to check: Can a new {entity/route/command/skill} be added by creating one new file + one registry entry? If adding a feature requires modifying >2 existing files, the design may need better extension points.

5. Security

• No hardcoded secrets, API keys, or credentials?
• User input sanitized before database queries, template rendering, file operations?
• Auth tokens have reasonable expiration and are stored securely?
• Error responses don't leak stack traces, internal paths, or system details?
• Dependencies from trusted sources? No eval() or exec() with external data?

How to check: Search for string concatenation in queries, raw user input in templates, hardcoded strings that look like keys/tokens, catch blocks that return internal errors.

Scope-Based Scaling

Scale review depth to the size of changes:

Change Size	Dimensions to Review
< 50 lines changed, ≤ 2 files	Simplicity only
50-200 lines changed OR 3-5 files	Simplicity + Modularity
200+ lines OR 6+ files	All five dimensions

Milestone boundary definition: A milestone boundary is reached when all tasks in that milestone have status 'done' and all post-task gates pass. Get the milestone diff with: git diff <sha-before-first-task-in-milestone> HEAD. If that SHA is unavailable, detect the default branch (git symbolic-ref refs/remotes/origin/HEAD, fall back to main) and use: git merge-base HEAD <default-branch>.

Loop Rules

1. One dimension at a time -- don't try to fix everything at once
2. Fix → re-check only the affected dimension (unless fix touches other areas)
3. Checkpoint before fixing -- before attempting fixes, commit current state with wip: prefix (preferred -- stashes are easily lost in multi-step flows). If 3 iterations fail, revert to the checkpoint and escalate.
4. Max 3 iterations per dimension -- beyond 3 indicates an architectural issue, not a code quality issue. Escalate to user with evidence of what was tried. In autonomous mode: mark the dimension as FAIL, document what was tried, revert to checkpoint, and continue to the next dimension. Report all failures at the end.
5. Evidence for each PASS -- state what was checked and why it passes
6. Autonomous up to iteration cap -- fix and re-check without human interaction. Only escalate when the cap is hit or when a fix would require design changes beyond the current scope. In autonomous mode, escalation = document and continue, not deadlock.

Output Format

## Autonomous Review: [milestone name]

### Optimization: PASS
- Checked: all 5 new functions, no O(n²) loops, no redundant I/O
- Evidence: main loop is O(n), single file read per config load

### Simplicity: PASS (2 iterations)
- Iteration 1: removed 3 unused imports in utils module, extracted TIMEOUT_MS = 5000
- Iteration 2: all clean
- Evidence: 0 dead code, 0 magic numbers, 0 duplicate logic

### Modularity: PASS
- Checked: 4 modules, each <150 lines, one-sentence purpose each
- Evidence: parser module parses, validator module validates, no circular deps

### Extensibility: PASS
- Checked: new skill type would require 1 new file + 1 registry entry
- Evidence: skill loading is plugin-based, no hardcoded skill list

### Security: PASS
- Checked: no hardcoded secrets, all user input sanitized, no eval() with external data
- Evidence: auth tokens stored in env vars, input validated before DB queries, error responses use generic messages

FAIL Output Template

When a dimension fails after 3 iterations:

### Modularity: FAIL (3 iterations, escalating)

**What was tried:**
- Iteration 1: Split parser module into tokenizer + parser → broke 3 tests
- Iteration 2: Fixed tests, but circular dependency between modules
- Iteration 3: Attempted dependency inversion → still has cross-module state

**Root cause:** Parser and validator share mutable state that can't be cleanly separated without redesigning the data flow.

**Recommendation:** Architectural redesign needed. Suggest brainstorming session for data flow refactor.

Transitions

Called by: mbscode:executing-plans or mbscode:subagent-driven-development at milestone boundaries; also referenced by HOOKS.md milestone hooks After completion: Continue to next milestone, or return to the caller (executing-plans or subagent-driven-development) which handles the transition to mbscode:finishing-a-development-branch when all milestones are done

Red Flags

Thought	Reality
"It's good enough"	Run the checklist. Show evidence.
"This dimension doesn't apply"	Check the Scope-Based Scaling table. Skip only if the change size is below the threshold for that dimension.
"I already checked this mentally"	Mental checks don't count. Show the evidence.
"The fix is trivial, skip re-check"	Trivial fixes break things. Re-check.
"3 iterations isn't enough"	If 3 iterations don't fix it, the problem is architectural. Escalate.