gastown/.beads/formulas/mol-polecat-chrome.formula.toml

description = """
Maximum rigor polecat workflow with deep context and triple review.

Chrome is for critical work where quality is paramount. Every phase is
decomposed into checkable atoms. Reviews are done three times. Context
is explicitly loaded before design begins.

## When to Use
- P0/P1 priority issues
- Security-sensitive changes
- Core architecture work
- Public API changes
- Anything that could break production

## Phases
1. **Deep Context** - Read strategic docs before starting
2. **Design** - Draft, review, finalize
3. **Implement** - Scaffold, core, edge cases
4. **Test** - Write, run, review
5. **Triple Review** - Three passes over the code
6. **Final** - Docs, cleanup, submit
"""
formula = "mol-polecat-chrome"
type = "workflow"
version = 1

# =============================================================================
# PHASE 1: DEEP CONTEXT
# =============================================================================

[[steps]]
id = "preflight"
title = "Load basic context"
description = """
Standard initialization.

```bash
gt prime                    # Load role context
bd prime                    # Load beads context
gt mol status               # Check your hook
bd show {{issue}}           # Full issue details
gt mail inbox               # Check for additional context
```

**Exit criteria:** Session initialized, issue understood."""

[[steps]]
id = "read-strategic-context"
title = "Read strategic context documents"
needs = ["preflight"]
description = """
CRITICAL: Read the strategic context before designing.

These documents contain the vision, principles, and architectural decisions
that should guide your implementation. Do not skip this step.

**1. Read CONTEXT.md:**
```bash
cat ~/gt/docs/hop/CONTEXT.md
```
This contains:
- Strategic vision
- Design principles
- What we're building and why

**2. Read PRIMING.md:**
```bash
cat ~/gt/docs/PRIMING.md
```
This contains:
- Role taxonomy
- Agent responsibilities
- System architecture

**3. Absorb and consider:**
- How does {{feature}} fit the strategic vision?
- What principles apply to this work?
- Are there architectural constraints to respect?

Take notes if helpful. This context shapes your design.

**Exit criteria:** You understand the strategic context and how it applies."""

# =============================================================================
# PHASE 2: DESIGN (Draft -> Review -> Finalize)
# =============================================================================

[[steps]]
id = "design-draft"
title = "Draft design for {{feature}}"
needs = ["read-strategic-context"]
description = """
Create an initial design based on strategic context.

Write a design document (can be comments, markdown, or mental model):

1. **Problem Statement**: What exactly are we solving?
2. **Approach**: How will we solve it?
3. **Files to Modify**: What code changes?
4. **Dependencies**: What does this depend on?
5. **Risks**: What could go wrong?
6. **Alternatives Considered**: What else could we do?

Be specific. Reference the strategic context where relevant.

**Exit criteria:** Draft design exists."""

[[steps]]
id = "design-review"
title = "Review your design"
needs = ["design-draft"]
description = """
Step back and critically review your draft design.

Questions to ask:
- Does this align with the strategic vision from CONTEXT.md?
- Is this the simplest solution that works?
- Have I considered all edge cases?
- What would break if my assumptions are wrong?
- Is this consistent with existing patterns in the codebase?
- Would another engineer understand this approach?

Look for:
- Over-engineering
- Missing edge cases
- Inconsistency with existing code
- Scope creep beyond {{issue}}

Revise the design based on this review.

**Exit criteria:** Design reviewed and improved."""

[[steps]]
id = "design-finalize"
title = "Finalize design"
needs = ["design-review"]
description = """
Lock in the design before implementation.

Final checklist:
- [ ] Approach is clear and justified
- [ ] All files to modify are identified
- [ ] Risks are acknowledged
- [ ] Success criteria are defined
- [ ] Design is consistent with strategic context

If you're uncertain about anything, now is the time to ask Witness:
```bash
gt mail send <rig>/witness -s "Design review: {{issue}}" -m "..."
```

Once finalized, commit to this design. Don't redesign mid-implementation.

**Exit criteria:** Design is final, ready to implement."""

# =============================================================================
# PHASE 3: IMPLEMENT (Scaffold -> Core -> Edge Cases)
# =============================================================================

[[steps]]
id = "implement-scaffold"
title = "Scaffold the structure"
needs = ["design-finalize"]
description = """
Create the skeleton before filling in logic.

1. Create new files if needed
2. Add function signatures with TODO bodies
3. Set up imports and dependencies
4. Add test file stubs

```bash
git add <files>
git commit -m "scaffold: structure for {{feature}} ({{issue}})"
```

This should compile/parse but not work yet.

**Exit criteria:** Structure exists, compiles, ready for core logic."""

[[steps]]
id = "implement-core"
title = "Implement core logic"
needs = ["implement-scaffold"]
description = """
Fill in the happy path - the main functionality.

Focus on:
- Primary use case working correctly
- Clear, readable code
- Following existing patterns

Don't worry about edge cases yet. Get the core working first.

```bash
git add <files>
git commit -m "feat: core logic for {{feature}} ({{issue}})"
```

**Exit criteria:** Core functionality works for the happy path."""

[[steps]]
id = "implement-edge-cases"
title = "Handle edge cases"
needs = ["implement-core"]
description = """
Now handle the edge cases identified in design.

For each edge case:
1. Add the handling code
2. Add a test for it
3. Verify it works

Common edge cases:
- Empty/nil inputs
- Boundary conditions
- Error conditions
- Concurrent access (if applicable)

```bash
git add <files>
git commit -m "feat: edge case handling for {{feature}} ({{issue}})"
```

**Exit criteria:** All known edge cases handled."""

# =============================================================================
# PHASE 4: TEST (Write -> Run -> Review)
# =============================================================================

[[steps]]
id = "test-write"
title = "Write comprehensive tests"
needs = ["implement-edge-cases"]
description = """
Write tests for all new code.

Test categories:
1. **Unit tests** - Test individual functions
2. **Integration tests** - Test component interaction
3. **Regression tests** - Prevent the bug from recurring

Coverage goals:
- Happy path tested
- Each edge case tested
- Error conditions tested
- Boundary conditions tested

```bash
git add *_test.go
git commit -m "test: add tests for {{feature}} ({{issue}})"
```

**Exit criteria:** Comprehensive test coverage for new code."""

[[steps]]
id = "test-run"
title = "Run full test suite"
needs = ["test-write"]
description = """
Run ALL tests, not just your new ones.

```bash
go test ./...               # Full test suite
go build ./...              # Build check
```

**ALL TESTS MUST PASS.**

If tests fail:
- Your code broke something: FIX IT
- Pre-existing failure: file bead, but still need green

Do not proceed until all tests pass.

**Exit criteria:** Full test suite passes."""

[[steps]]
id = "test-review"
title = "Review test coverage"
needs = ["test-run"]
description = """
Verify tests are actually meaningful.

Check each test:
- Does it test real behavior, not implementation details?
- Could a bug slip past this test?
- Are assertions specific enough?

Look for:
- Missing negative tests (what should NOT happen)
- Missing boundary tests
- Tests that always pass (useless)
- Tests that test mocks instead of real code

Add any missing tests.

**Exit criteria:** Tests are comprehensive and meaningful."""

# =============================================================================
# PHASE 5: TRIPLE REVIEW
# =============================================================================

[[steps]]
id = "code-review-1"
title = "Code review pass 1: Correctness"
needs = ["test-review"]
description = """
First review pass: Is the code CORRECT?

```bash
git diff origin/main...HEAD
```

Focus on:
- Logic errors
- Off-by-one bugs
- Null pointer risks
- Race conditions
- Resource leaks
- Error handling gaps

For each issue found: FIX IT, don't just note it.

**Exit criteria:** No correctness issues remain."""

[[steps]]
id = "code-review-2"
title = "Code review pass 2: Security"
needs = ["code-review-1"]
description = """
Second review pass: Is the code SECURE?

Review for OWASP Top 10:
- Injection (SQL, command, path)
- Broken authentication
- Sensitive data exposure
- XXE
- Broken access control
- Security misconfiguration
- XSS
- Insecure deserialization
- Using components with known vulnerabilities
- Insufficient logging

Also check:
- Secrets not hardcoded
- Input validation
- Output encoding
- Proper error messages (don't leak info)

**Exit criteria:** No security issues remain."""

[[steps]]
id = "code-review-3"
title = "Code review pass 3: Quality"
needs = ["code-review-2"]
description = """
Third review pass: Is the code QUALITY?

Check:
- Naming: Are names clear and consistent?
- Structure: Is code well-organized?
- Comments: Are complex parts explained?
- DRY: Is there unnecessary duplication?
- SOLID: Are principles followed?
- Patterns: Does it match codebase conventions?
- Cruft: Any debug code, TODOs, dead code?

The code should be something you're proud of.

**Exit criteria:** Code is clean, maintainable, follows conventions."""

# =============================================================================
# PHASE 6: FINAL
# =============================================================================

[[steps]]
id = "docs-update"
title = "Update documentation"
needs = ["code-review-3"]
description = """
Update any affected documentation.

Check:
- README if user-facing changes
- Code comments for complex logic
- API docs if interfaces changed
- CHANGELOG if applicable

```bash
git add docs/ *.md
git commit -m "docs: update for {{feature}} ({{issue}})"
```

**Exit criteria:** Documentation reflects the changes."""

[[steps]]
id = "final-check"
title = "Final pre-submit check"
needs = ["docs-update"]
description = """
One last verification before submit.

```bash
# Clean state
git status                  # Must be clean
git stash list              # Must be empty

# Tests still pass
go test ./...

# Review commit history
git log --oneline origin/main..HEAD

# Review final diff
git diff origin/main...HEAD --stat
```

If anything is wrong, fix it before proceeding.

**Exit criteria:** Everything is perfect."""

[[steps]]
id = "postflight"
title = "Submit for merge"
needs = ["final-check"]
description = """
Push and signal completion.

```bash
# Push branch
git push -u origin $(git branch --show-current)

# Close issue with summary
bd close {{issue}} --reason "Implemented with chrome workflow: {{feature}}"
bd sync

# Signal done
gt done
```

Witness will verify, send to merge queue, and terminate your session.

**Exit criteria:** Witness takes over from here."""

[vars]
[vars.issue]
description = "The issue ID assigned to this polecat"
required = true
[vars.feature]
description = "The feature being implemented"
required = true