@titan-design/brain 0.6.1 → 0.7.0

package/dist/templates/planning-design.md

@@ -0,0 +1,162 @@
+# Planning Design: {{TASK_ID}}
+
+Produce design artifacts for a planning workflow. Read the research brief, synthesize with interview answers (if provided), and write spec, design, and acceptance criteria. Do NOT implement or write code — only produce design documents.
+
+---
+
+## Setup
+
+- Plan: `{{PLAN_ID}}`
+- Project: `{{PROJECT_PREFIX}}`
+- Location: `{{REPO_PATH}}`
+- Complexity: {{COMPLEXITY}}
+- Build: `{{BUILD_CMD}}` | Test: `{{TEST_CMD}}` | Typecheck: `{{TYPECHECK_CMD}}` | Lint: `{{LINT_CMD}}`
+
+## Input
+
+### Research Brief
+
+Read `{{REPO_PATH}}/.plans/{{PLAN_ID}}/research-brief.md` for context gathered during the research phase. This is your primary source of truth for existing code, patterns, constraints, and external findings.
+
+### Interview Answers (high complexity only)
+
+{{INTERVIEW_ANSWERS}}
+
+### Task Description
+
+{{TASK_DESCRIPTION}}
+
+## Instructions
+
+Produce three artifacts in `{{REPO_PATH}}/.plans/{{PLAN_ID}}/`. These documents are the contract for all subsequent phases — critic review, spec tests, work decomposition, and implementation. Be concrete: file paths, type signatures, function names. The decompose phase uses these to create implementation tasks with file ownership.
+
+### Artifact 1: spec.md
+
+Write `{{REPO_PATH}}/.plans/{{PLAN_ID}}/spec.md` — the problem specification.
+
+```markdown
+# Spec: <feature name>
+
+## Problem
+[What problem does this solve? What happens without it? 2-3 sentences.]
+
+## Requirements
+[Numbered list of functional requirements. Each must be testable.]
+
+## Constraints
+[What can't change. Backward compatibility. Performance bounds. API contracts.]
+
+## Out of Scope
+[Explicit list of what this work does NOT include.]
+
+## Dependencies
+[Other systems, packages, or tasks this depends on.]
+```
+
+Keep it to 1-2 pages. Reference interview answers where applicable.
+
+### Artifact 2: design.md
+
+Write `{{REPO_PATH}}/.plans/{{PLAN_ID}}/design.md` — the technical approach.
+
+```markdown
+# Design: <feature name>
+
+## Approach
+[2-3 paragraph summary of the technical approach.]
+
+## Files to Create/Modify
+[Exact paths for every file that will be created or modified.]
+
+| Action | Path | Purpose |
+|--------|------|---------|
+| Create | `src/features/foo.ts` | Core logic for X |
+| Modify | `src/store/bar.ts` | Add Y state |
+| Create | `src/__tests__/foo.test.ts` | Tests for X |
+
+## API Shapes / Type Signatures
+[TypeScript interfaces, function signatures, or data structures. Concrete, not abstract.]
+
+## Data Flow
+[How data moves through the system. Which components talk to which.]
+
+## Key Decisions
+
+| Decision | Chosen | Alternative | Rationale |
+|----------|--------|-------------|-----------|
+| State management | Zustand | Context | Simpler API, existing pattern |
+
+## Risks and Mitigations
+[What could go wrong. How to handle it.]
+
+## Scaffolding vs. Implementation
+[What should be built first (wave 1) vs. what can be parallelized (wave 2+).]
+- **Scaffolding (wave 1):** [types, interfaces, shared utilities, store structure]
+- **Implementation (wave 2+):** [features that can be built in parallel on top of scaffolding]
+
+## PR Boundaries
+[Should this be one PR or multiple? If multiple, what is the boundary?]
+- Option A: One PR for everything (simpler review, all-or-nothing)
+- Option B: One PR per wave (incremental, reviewable chunks)
+- Recommendation: [chosen option with rationale]
+```
+
+### Artifact 3: acceptance-criteria.md
+
+Write `{{REPO_PATH}}/.plans/{{PLAN_ID}}/acceptance-criteria.md` — testable conditions.
+
+```markdown
+# Acceptance Criteria: <feature name>
+
+## Criteria
+
+### AC-01: <short name>
+**Given:** <precondition>
+**When:** <action>
+**Then:** <expected result>
+
+### AC-02: <short name>
+**Given:** <precondition>
+**When:** <action>
+**Then:** <expected result>
+
+[Continue for all criteria...]
+
+## Edge Cases
+
+### EC-01: <short name>
+**Given:** <edge condition>
+**When:** <action>
+**Then:** <expected behavior>
+
+## Non-Functional
+
+### NF-01: <short name>
+[Performance, accessibility, or other non-functional requirement with measurable threshold]
+```
+
+Every requirement in spec.md must map to at least one acceptance criterion. Every acceptance criterion must be testable — no vague conditions like "works correctly."
+
+## Quality Checks
+
+Before reporting, verify your artifacts:
+
+- Every spec requirement has a corresponding AC
+- Every AC uses Given/When/Then format with concrete, testable conditions
+- design.md files table has exact paths (no placeholders like `src/...`)
+- API shapes include TypeScript types, not prose descriptions
+- Key decisions table has at least one entry with a considered alternative
+- Scaffolding section clearly separates wave 1 (blocking) from wave 2+ (parallelizable)
+- PR boundaries section has a concrete recommendation
+
+## Output
+
+When complete, report to the orchestrator:
+
+- **Design approach** — 3-5 sentence summary of the technical approach
+- **Files** — count of files to create and modify
+- **Acceptance criteria** — count of ACs, edge cases, and non-functional criteria
+- **Key decisions** — list of decisions made (one line each)
+- **Open questions** — any unresolved questions that need human input before implementation proceeds
+
+Stay in design mode. Do not write implementation code, tests, or make changes to the codebase. Flag ambiguity as open questions rather than resolving it with assumptions.

package/dist/templates/planning-interview.md

@@ -0,0 +1,74 @@
+# Planning Interview Guide
+
+## When to Use
+
+This guide is for the **orchestrator** (not a sub-agent). Use it during the interview phase of the planning workflow for **high-complexity** tasks. The orchestrator asks questions one at a time in the active session, not as a batch.
+
+## Prerequisites
+
+Before starting the interview:
+- Research phase must be complete
+- Read `.plans/{{PLAN_ID}}/research-brief.md` for context
+- Have the task description ready: {{TASK_DESCRIPTION}}
+
+## Interview Flow
+
+Ask these questions **one at a time**. Wait for the answer before proceeding. Adapt follow-ups based on responses.
+
+### Core Questions
+
+**1. Problem Framing**
+> "What specific problem does this solve? What happens if we don't build it?"
+
+Listen for: clarity of problem statement, urgency, impact scope.
+
+**2. Constraints**
+> "What can't change? What existing behavior must be preserved?"
+
+Listen for: backward compatibility requirements, performance constraints, API contracts.
+
+**3. Scope Boundary**
+> "What's explicitly out of scope for this work?"
+
+Listen for: feature creep risks, adjacent work that should be separate tasks.
+
+**4. Success Criteria**
+> "How will we know this works? What would you test manually?"
+
+Listen for: testable conditions that become acceptance criteria.
+
+**5. Prior Art**
+> "Is there existing code that does something similar? Any patterns we should follow or avoid?"
+
+Listen for: reusable code, anti-patterns from past experience.
+
+### Research-Informed Follow-ups
+
+Based on the research brief, ask targeted questions about:
+- Knowledge gaps identified in research (ask the human to fill them)
+- Competing approaches found (ask which direction the human prefers)
+- Risks identified (ask about acceptable trade-offs)
+
+Example: "Research found that [X approach] and [Y approach] are both viable. [X] is simpler but [Y] handles [edge case]. Which direction do you lean?"
+
+### Complexity Reassessment
+
+After the interview, reassess complexity:
+- If answers reveal the task is simpler than expected: keep current complexity level (complexity only goes UP)
+- If answers reveal cross-cutting concerns, new patterns, or architectural decisions not in the original description: escalate to high complexity
+- If the human identifies prerequisites or decomposition needs: note for the decompose phase
+
+## Recording Answers
+
+Do NOT write answers to a file. Keep them in orchestrator context for passing to the design agent. The design agent receives interview answers as part of its {{INTERVIEW_ANSWERS}} variable.
+
+## Output
+
+After the interview, the orchestrator should have:
+1. Validated assumptions from the research brief
+2. Clear scope boundaries
+3. Testable success criteria (raw, to be formalized in acceptance-criteria.md)
+4. Complexity assessment (confirmed or escalated)
+5. Any new research questions to investigate before design
+
+If new research is needed, dispatch a targeted research agent before proceeding to design.

package/dist/templates/planning-research.md

@@ -0,0 +1,114 @@
+# Planning Research: {{TASK_ID}}
+
+Explore-type agent gathering context for a planning workflow. Read broadly, produce a structured brief. Do NOT design or implement — only gather information.
+
+---
+
+## Setup
+
+- Plan: `{{PLAN_ID}}`
+- Project: `{{PROJECT_PREFIX}}`
+- Location: `{{REPO_PATH}}`
+- Output: `.plans/{{PLAN_ID}}/research-brief.md`
+
+## Task
+
+{{TASK_DESCRIPTION}}
+
+## Focus Areas
+
+{{RESEARCH_FOCUS}}
+
+## Instructions
+
+Work through each research area below. Spend proportional effort on the focus areas listed above.
+
+### 1. Codebase Exploration
+
+Search the codebase at `{{REPO_PATH}}` for:
+
+- **Related code** — existing features, shared utilities, similar patterns. Use grep/glob to find relevant files.
+- **Test patterns** — how are tests structured? What frameworks, helpers, and conventions are used?
+- **Configuration** — read CLAUDE.md, eslint config, tsconfig. Note conventions that constrain the design.
+- **Recent activity** — `git log --oneline -20 -- <relevant paths>` to see what's been changing nearby.
+
+Record file paths and brief descriptions. Quote key code only when the exact text matters.
+
+### 2. Documentation Review
+
+Read:
+
+- Project README and CLAUDE.md at `{{REPO_PATH}}`
+- Any design docs in `docs/` or `.plans/`
+- Inline documentation in related files
+- Brain KB: `brain search "<relevant terms>"` (if brain CLI is available)
+
+### 3. External Research
+
+Search for:
+
+- Best practices for the problem domain
+- Similar implementations in open source projects
+- Known pitfalls and anti-patterns
+- Relevant blog posts, papers, or documentation
+
+Cite sources. Prefer authoritative references (official docs, well-known projects) over random blog posts.
+
+### 4. Produce Research Brief
+
+Create the directory if needed:
+
+```bash
+mkdir -p {{REPO_PATH}}/.plans/{{PLAN_ID}}
+```
+
+Write your findings to `{{REPO_PATH}}/.plans/{{PLAN_ID}}/research-brief.md` using this structure:
+
+```markdown
+# Research Brief: {{TASK_ID}}
+
+Plan: {{PLAN_ID}} | Project: {{PROJECT_PREFIX}}
+
+## Existing Code
+
+- [relevant files with absolute paths and what they do]
+- [patterns and conventions observed]
+- [test infrastructure and conventions]
+
+## External Findings
+
+- [best practices with sources/links]
+- [similar solutions found in open source]
+- [relevant research or documentation]
+
+## Knowledge Gaps
+
+- [things you could not determine from available sources]
+- [areas where multiple valid approaches exist and a decision is needed]
+- [assumptions that need human validation]
+
+## Recommendations
+
+- [specific approaches worth considering, with trade-offs]
+- [risks identified and potential mitigations]
+
+## Suggested Interview Questions
+
+Based on the knowledge gaps above, these questions would help clarify the design:
+
+1. [question targeting the most critical knowledge gap]
+2. [question about scope or constraints]
+3. [question about priorities or trade-offs]
+4. [additional questions as needed, aim for 3-5 total]
+```
+
+## Output
+
+When complete, report to the orchestrator:
+
+- **Key findings** — 3-5 bullet point summary of the most important discoveries
+- **Knowledge gaps** — count and brief list of unresolved questions
+- **Interview questions** — the suggested questions from the brief (if any)
+- **Research brief path** — absolute path to the written file
+
+Stay in research mode. Do not propose implementations, write code, or make design decisions. Flag ambiguity as knowledge gaps rather than resolving it yourself.

package/dist/templates/planning-spectests.md

@@ -0,0 +1,84 @@
+# Planning Spec Tests: {{TASK_ID}}
+
+## Context
+
+- Plan: {{PLAN_ID}}
+- Project: {{PROJECT_PREFIX}}
+- Location: `{{REPO_PATH}}`
+- Test command: `{{TEST_CMD}}`
+
+## Input Artifacts
+
+Read these files before writing any tests:
+
+1. `.plans/{{PLAN_ID}}/acceptance-criteria.md` — the testable conditions to implement
+2. `.plans/{{PLAN_ID}}/design.md` — the technical approach (for understanding API shapes and data flow)
+
+## Your Task
+
+Write failing test files that map each acceptance criterion to one or more test cases. These tests are the executable specification — they define what "done" means for the implementation agent.
+
+### Rules
+
+1. **One test per acceptance criterion minimum** — every Given/When/Then in acceptance-criteria.md must have a corresponding test
+2. **Arrange-Act-Assert structure** — clear setup, action, assertion in every test
+3. **Follow project conventions** — use the same test framework (Vitest), file naming patterns, and import styles as existing tests in the repo
+4. **Tests MUST fail** — you are writing tests before implementation exists. If a test passes, either the feature already exists (check!) or the test is wrong
+5. **No implementation code** — do not create source files, stubs, or mocks for the feature being tested. Import paths should reference where the code WILL be (per design.md)
+6. **Descriptive test names** — test names describe the scenario, not the method (e.g., "creates active session when user has no existing sessions" not "test createSession")
+
+### Process
+
+For each acceptance criterion in acceptance-criteria.md:
+
+1. Read the criterion
+2. Determine which file(s) the test belongs in (based on design.md file paths)
+3. Write the test using Arrange-Act-Assert
+4. Add edge case tests where the criterion implies boundary conditions
+
+### Test File Placement
+
+Place test files in the project's standard test directory, following existing patterns:
+- If tests live in `__tests__/`, put them there
+- If tests live alongside source as `*.test.ts`, follow that pattern
+- Mirror the source file structure from design.md
+
+## Verification
+
+After writing all test files, run `{{TEST_CMD}}` and confirm failures. Compilation errors from missing imports are expected and acceptable — they prove the tests reference code that does not yet exist.
+
+If any test passes unexpectedly, investigate: the feature may already exist, or the test assertion is wrong. Fix the test so it fails for the right reason.
+
+## Handoff
+
+After writing and verifying all test files:
+
+1. **Do NOT commit** — these tests are pre-implementation artifacts
+2. **Git stash the tests** — run:
+   ```bash
+   cd {{REPO_PATH}}
+   git add <test files you created>
+   git stash push -m "spec-tests-{{PLAN_ID}}" -- <test files>
+   ```
+3. **Report** using the output format below
+
+## Output
+
+```
+## Spec Test Summary
+
+### Tests Written
+- <file path> — <N> tests covering criteria: <list of criteria IDs>
+
+### Coverage
+- Total acceptance criteria: <N>
+- Criteria with tests: <N>
+- Criteria without tests: <N> (explain why if any)
+
+### Stash Reference
+- `git stash list` entry: spec-tests-{{PLAN_ID}}
+
+### Notes
+- <any assumptions made about API shapes>
+- <any criteria that were ambiguous>
+```

package/dist/templates/review-agent.md

@@ -0,0 +1,155 @@
+# PR Review Agent Template
+
+Blank-slate code review for a GitHub PR. Fill in variables and pass as agent prompt.
+
+---
+
+## Variables
+
+| Variable | Description | Example |
+|----------|-------------|---------|
+| `{{OWNER}}` | GitHub repo owner | `voltras` |
+| `{{REPO}}` | GitHub repo name | `mobile` |
+| `{{PR_NUMBER}}` | Pull request number | `42` |
+| `{{BRANCH}}` | Feature branch name | `feat/android-mvp` |
+| `{{BASE}}` | Base branch to diff against | `main` |
+| `{{REPO_PATH}}` | Absolute path to repo on disk | `/Users/hjewkes/Documents/projects/voltras-workspace/voltras/mobile` |
+| `{{PROJECT_PREFIX}}` | Project key from project-map.json | `VLT` |
+| `{{REVIEW_THRESHOLD}}` | Risk score that triggers human review | `4` |
+
+---
+
+## Agent Prompt
+
+You are reviewing PR #{{PR_NUMBER}} in {{OWNER}}/{{REPO}}.
+
+Branch: `{{BRANCH}}` targeting `{{BASE}}`
+Repo path: `{{REPO_PATH}}`
+Project: `{{PROJECT_PREFIX}}` | Human review threshold: `{{REVIEW_THRESHOLD}}`
+
+### Step 1: Read the full diff
+
+```bash
+cd {{REPO_PATH}} && git fetch origin && git diff {{BASE}}...{{BRANCH}}
+```
+
+### Step 2: Read all changed files in full
+
+List changed files:
+
+```bash
+cd {{REPO_PATH}} && git diff --name-only {{BASE}}...{{BRANCH}}
+```
+
+Read every changed file in its entirety (not just the diff hunks). You need surrounding context to evaluate correctness, naming, architecture, and test adequacy.
+
+### Step 3: Review against checklist
+
+For EVERY finding, assign one of:
+- `[FIX]` — Must fix before merge. Explain why.
+- `[WON'T FIX: <reason>]` — Acceptable as-is. Explain why.
+
+There is no "suggestion" category. Decide: fix it or justify leaving it.
+
+**Checklist:**
+
+1. **Code quality** — naming, readability, function length (max ~30 lines), dead code, commented-out code
+2. **Edge cases** — invalid inputs, null/undefined, boundary conditions, empty collections
+3. **Error handling** — failures handled at boundaries, missing guards, swallowed errors
+4. **Test coverage** — adequate tests? missing scenarios? tests verify behavior not implementation? Arrange-Act-Assert?
+5. **Backwards compatibility** — does existing behavior change? are defaults preserved? breaking API changes?
+6. **Architecture** — coupling, abstraction quality, separation of concerns, composition over inheritance
+7. **Performance** — unnecessary allocations, O(n) where O(1) possible, memory leaks, redundant re-renders
+8. **Type safety** — exhaustive switches, unchecked casts, `any` types, missing generics
+9. **Security** — injection risks, sensitive data exposure, path traversal, shell injection
+
+### Step 4: Post a GitHub review with inline comments
+
+Separate your findings into two groups:
+
+**A. Line-specific findings** — these become inline comments. Comments can ONLY target lines that appear in the diff (changed lines plus ~3 lines of surrounding context). Use `side: "RIGHT"` for the new file version (99% of cases) and `side: "LEFT"` for deleted lines only.
+
+**B. Structural/architectural findings** — these go in the top-level review body. Include anything that does not map to a specific diff line: missing tests, architectural concerns, naming patterns across files, etc.
+
+Post the review using the verified API pattern below. This is the ONLY reliable method — do not use alternative approaches.
+
+```bash
+OWNER="{{OWNER}}"
+REPO="{{REPO}}"
+PR_NUMBER={{PR_NUMBER}}
+
+echo '{
+  "event": "COMMENT",
+  "body": "## Code Review\n\nVerdict: <PASS or NEEDS WORK>\n\n### Summary\n<high-level summary of the changes and overall quality>\n\n### Structural Findings\n<any findings that do not map to a specific diff line>\n\n### FIX Items\n<numbered list of all FIX items, or \"None\" if verdict is PASS>",
+  "comments": [
+    {
+      "path": "<relative file path>",
+      "line": <line number in the new file>,
+      "side": "RIGHT",
+      "body": "[FIX] <description of the issue and why it must be fixed>"
+    }
+  ]
+}' | gh api "repos/$OWNER/$REPO/pulls/$PR_NUMBER/reviews" \
+  -X POST --input -
+```
+
+**Critical constraints for the API call:**
+- `comments` array can be empty `[]` if all findings are structural
+- Each comment `line` must be a line number visible in the diff — not arbitrary file lines
+- Use `start_line` and `start_side` for multi-line comment ranges
+- `commit_id` is optional and defaults to PR HEAD
+- Do NOT use `pulls/{id}/comments` endpoint — it requires `position` (diff offset), not `line`
+- Do NOT use `-f` / `-F` flags for nested objects — use `--input -` with piped JSON
+- Submitted reviews (`event: "COMMENT"`) cannot be deleted — double-check before posting
+- Build the JSON programmatically if there are many comments to avoid syntax errors
+
+### Step 5: Assess risk level
+
+Score the PR on a 1–5 risk scale:
+
+| Score | Criteria | Examples |
+|-------|----------|----------|
+| 1 | Docs, comments, test-only, config formatting | README update, adding test cases |
+| 2 | Internal refactors, dead code removal, minor dep bumps | Rename internal function, remove unused import |
+| 3 | New features within existing patterns, non-breaking additions | New endpoint following existing conventions |
+| 4 | API changes, new patterns, cross-cutting changes, user-facing behavior | New state management approach, UI flow change |
+| 5 | Security-sensitive, protocol/NDA data, breaking API, publishing | Auth changes, protocol byte changes, npm publish |
+
+**Scoring rules:**
+- Use the HIGHEST applicable score across all changes in the PR
+- Any change touching files matching `**/protocol/**`, `**/auth/**`, or `**/security/**` is automatically risk 4+
+- Publishing workflows (npm publish, app store, release scripts) are automatically risk 5
+- If unsure between two levels, round UP
+
+### Step 6: Determine verdict
+
+- **PASS** — No `[FIX]` items remain. Code is ready to merge.
+- **NEEDS WORK** — One or more `[FIX]` items exist. List them.
+
+### Step 7: Output orchestrator summary
+
+After posting the review, output a structured summary for the orchestrator (not posted to GitHub):
+
+```
+## Orchestrator Summary
+
+### Verdict: <PASS or NEEDS WORK>
+### Risk: <1-5>
+
+### FIX Items (<count>)
+- <file:line> — <brief description>
+
+### High-Complexity Areas (human attention recommended)
+- <area and why it needs human review>
+
+### Open Questions
+- <any ambiguity about requirements or approach>
+
+### Security Concerns
+- <any security issues, or "None">
+
+### Estimated Fix Effort
+- <trivial / small / medium — to help orchestrator decide whether to resume agent or re-review>
+```
+
+The orchestrator uses the risk score and verdict to route the review — see `coordination/scripts/review-route.sh`.

package/dist/templates/review-fixup.md

@@ -0,0 +1,79 @@
+# Review Fixup: {{TASK_ID}}
+
+## Setup
+
+- Location: `{{REPO_PATH}}`
+- Branch: `{{BRANCH_NAME}}`
+- PR: `{{OWNER}}/{{REPO}}#{{PR_NUMBER}}`
+- Build: `{{BUILD_CMD}}` | Test: `{{TEST_CMD}}` | Typecheck: `{{TYPECHECK_CMD}}` | Lint: `{{LINT_CMD}}`
+
+## Step 1: Fetch review comments
+
+```bash
+cd {{REPO_PATH}} && git checkout {{BRANCH_NAME}} && git pull origin {{BRANCH_NAME}}
+```
+
+```bash
+gh api repos/{{OWNER}}/{{REPO}}/pulls/{{PR_NUMBER}}/reviews --jq '.[].body'
+gh api repos/{{OWNER}}/{{REPO}}/pulls/{{PR_NUMBER}}/comments --jq '.[] | {path, line, body}'
+```
+
+## Step 2: Categorize findings
+
+Parse each comment. Extract items tagged `[FIX]` — these are required changes. Skip items tagged `[WON'T FIX]` or purely informational comments. Build a checklist of actionable fixes with file path, line, and description.
+
+## Step 3: Implement fixes
+
+For each `[FIX]` item:
+
+1. Read the referenced file in full
+2. Implement the fix
+3. Re-read the file to confirm the change addresses the comment
+
+Stay within the files referenced by review comments. Do not refactor unrelated code.
+
+## Step 4: Verify
+
+Run in order — all must pass:
+
+1. `{{TYPECHECK_CMD}}`
+2. `{{TEST_CMD}}`
+3. `{{LINT_CMD}}`
+4. `npx prettier --check .` — fix with `npx prettier --write .` if needed
+5. `{{BUILD_CMD}}`
+
+**Retry policy:** If any step fails, investigate and fix. Try at least **twice** before giving up. On failure after 2 attempts, report: (1) what is failing, (2) what you tried, (3) your theory on root cause.
+
+## Step 5: Commit
+
+Stage only changed files — do not use `git add -A` or `git add .`.
+
+```bash
+cd {{REPO_PATH}}
+git add <changed files>
+git commit -m "Address review feedback for {{TASK_ID}}"
+```
+
+Do NOT push — the orchestrator handles push and follow-up.
+
+## Step 6: Report
+
+```
+## Fixup Summary
+
+### Fixed (<count>)
+- <file:line> -- <what was fixed>
+
+### Skipped (<count>)
+- <file:line> -- <reason skipped (WON'T FIX / informational)>
+
+### Verification
+- Typecheck: PASS/FAIL
+- Tests: PASS/FAIL (<count> tests)
+- Lint: PASS/FAIL
+- Prettier: PASS/FAIL
+- Build: PASS/FAIL
+
+### Issues
+- <any problems encountered, or "None">
+```