gastown/internal/formula/formulas/mol-polecat-code-review.formula.toml

description = """
Review code and file beads for issues found.

This molecule guides a polecat through a code review task - examining a portion
of the codebase for bugs, security issues, code quality problems, or improvement
opportunities. The output is a set of beads capturing actionable findings.

## Polecat Contract (Self-Cleaning Model)

You are a self-cleaning worker. You:
1. Receive work via your hook (pinned molecule + review scope)
2. Work through molecule steps using `bd ready` / `gt mol step done <step>`
3. Complete and self-clean via `gt done` (submit findings + nuke yourself)
4. You are GONE - your findings are recorded in beads

**Fresh context:** Each `gt mol step done` respawns your session with fresh context.
This ensures each review step gets unbiased attention.

**Self-cleaning:** When you run `gt done`, you submit your findings, nuke your
sandbox, and exit. There is no idle state. Done means gone.

**Important:** This formula defines the template. Your molecule already has step
beads created from it. Use `bd ready` to find them - do NOT read this file directly.

**You do NOT:**
- Fix the issues yourself (file beads, let other polecats fix)
- Scope creep into unrelated areas
- Wait for someone to act on findings (you're done after filing)

## Variables

| Variable | Source | Description |
|----------|--------|-------------|
| scope | hook_bead | What to review (file path, directory, or description) |
| issue | hook_bead | The tracking issue for this review task |
| focus | hook_bead | Optional focus area (security, performance, etc.) |

## Failure Modes

| Situation | Action |
|-----------|--------|
| Scope too broad | Mail Witness, request narrower scope |
| Can't understand code | Mail Witness for context |
| Critical issue found | Mail Witness immediately, then continue |"""
formula = "mol-polecat-code-review"
version = 1

[[steps]]
id = "load-context"
title = "Load context and understand the review scope"
description = """
Initialize your session and understand what you're reviewing.

**1. Prime your environment:**
```bash
gt prime                    # Load role context
bd prime                    # Load beads context
```

**2. Check your hook:**
```bash
gt hook               # Shows your pinned molecule and hook_bead
```

The hook_bead describes your review scope. Read the tracking issue:
```bash
bd show {{issue}}           # Full issue details
```

**3. Understand the scope:**
- What files/directories are in scope?
- Is there a specific focus (security, performance, correctness)?
- What's the context - why is this review happening?

**4. Locate the code:**
```bash
# If scope is a path:
ls -la {{scope}}
head -100 {{scope}}         # Quick look at the code

# If scope is a directory:
find {{scope}} -type f -name "*.go" | head -20
```

**5. Check for recent changes:**
```bash
git log --oneline -10 -- {{scope}}
```

**Exit criteria:** You understand what you're reviewing and why."""

[[steps]]
id = "survey-code"
title = "Survey the code structure"
needs = ["load-context"]
description = """
Get a high-level understanding before diving into details.

**1. Understand the structure:**
```bash
# For a directory:
tree {{scope}} -L 2

# For a file:
wc -l {{scope}}             # How big is it?
```

**2. Identify key components:**
- What are the main types/structs?
- What are the public functions?
- What are the dependencies?

**3. Read the tests (if any):**
```bash
find {{scope}} -name "*_test.go" | xargs head -50
```
Tests often reveal intended behavior.

**4. Note initial impressions:**
- Is the code well-organized?
- Are there obvious patterns or anti-patterns?
- What areas look risky?

**Exit criteria:** You have a mental map of the code structure."""

[[steps]]
id = "detailed-review"
title = "Perform detailed code review"
needs = ["survey-code"]
description = """
Systematically review the code for issues.

**Review checklist:**

| Category | Look For |
|----------|----------|
| **Correctness** | Logic errors, off-by-one, nil handling, race conditions |
| **Security** | Injection, auth bypass, secrets in code, unsafe operations |
| **Error handling** | Swallowed errors, missing checks, unclear error messages |
| **Performance** | N+1 queries, unnecessary allocations, blocking calls |
| **Maintainability** | Dead code, unclear naming, missing comments on complex logic |
| **Testing** | Untested paths, missing edge cases, flaky tests |

**Focus on {{focus}} if specified.**

**1. Read through the code:**
```bash
cat {{scope}}               # For single file
# Or read files systematically for a directory
```

**2. For each issue found, note:**
- File and line number
- Category (bug, security, performance, etc.)
- Severity (critical, high, medium, low)
- Description of the issue
- Suggested fix (if obvious)

**3. Don't fix issues yourself:**
Your job is to find and report, not fix. File beads.

**Exit criteria:** You've reviewed all code in scope and noted issues."""

[[steps]]
id = "prioritize-findings"
title = "Prioritize and categorize findings"
needs = ["detailed-review"]
description = """
Organize your findings by priority and category.

**Priority levels:**

| Priority | Description | Action |
|----------|-------------|--------|
| P0 | Security vulnerability, data loss risk | Mail Witness immediately |
| P1 | Bug affecting users, broken functionality | File as bug, high priority |
| P2 | Code quality issue, potential future bug | File as task |
| P3 | Improvement opportunity, nice-to-have | File as task, low priority |

**1. Sort your findings:**
Group by priority, then by category.

**2. For P0 issues:**
```bash
gt mail send {{rig}}/witness -s "CRITICAL: Security issue found" -m "Scope: {{scope}}
Issue: {{issue}}
Finding: <description of critical issue>
Location: <file:line>"
```

**3. Prepare bead descriptions:**
For each finding, prepare:
- Clear title
- File/line location
- Description of the issue
- Why it matters
- Suggested fix (if known)

**Exit criteria:** Findings prioritized and ready to file."""

[[steps]]
id = "file-beads"
title = "File beads for all findings"
needs = ["prioritize-findings"]
description = """
Create beads for each finding.

**1. For bugs (P0, P1):**
```bash
bd create --type=bug --priority=1 \
  --title="<clear description of bug>" \
  --description="Found during code review of {{scope}}.

Location: <file:line>

Issue:
<description>

Impact:
<why this matters>

Suggested fix:
<if known>"
```

**2. For code quality issues (P2, P3):**
```bash
bd create --type=task --priority=2 \
  --title="<clear description>" \
  --description="Found during code review of {{scope}}.

Location: <file:line>

Issue:
<description>

Suggestion:
<how to improve>"
```

**3. Track filed beads:**
Note each bead ID as you create them.

**4. If no issues found:**
That's a valid outcome! Note that the code review passed.

**Exit criteria:** All findings filed as beads."""

[[steps]]
id = "summarize-review"
title = "Summarize review results"
needs = ["file-beads"]
description = """
Update the tracking issue with review summary.

**1. Create summary:**
```bash
bd update {{issue}} --notes "Code review complete.

Scope: {{scope}}
Focus: {{focus}}

Findings:
- P0 (critical): <count>
- P1 (high): <count>
- P2 (medium): <count>
- P3 (low): <count>

Beads filed:
<list of bead IDs>

Overall assessment:
<brief summary - healthy, needs attention, significant issues, etc.>"
```

**2. Sync beads:**
```bash
bd sync
```

**Exit criteria:** Tracking issue updated with summary."""

[[steps]]
id = "complete-and-exit"
title = "Complete review and self-clean"
needs = ["summarize-review"]
description = """
Signal completion and clean up. You cease to exist after this step.

**Self-Cleaning Model:**
Once you run `gt done`, you're gone. The command:
1. Syncs beads (final sync)
2. Nukes your sandbox
3. Exits your session immediately

**Run gt done:**
```bash
gt done
```

**What happens next (not your concern):**
- Other polecats may be assigned to fix the issues you found
- Witness may escalate critical findings
- The codebase improves based on your findings

You are NOT involved in any of that. You're gone. Done means gone.

**Exit criteria:** Beads synced, sandbox nuked, session exited."""

[vars]
[vars.scope]
description = "What to review - file path, directory, or description"
required = true

[vars.issue]
description = "The tracking issue for this review task"
required = true

[vars.focus]
description = "Optional focus area (security, performance, correctness, etc.)"
required = false