implement-sprint.md

gistfile1.txt

# Implement Sprint

Automated sprint implementation. Runs all phases without stopping, presents results for approval.

## Prerequisites

- Sprint spec exists at `docs/sprints/current/spec.md`
- Sprint state at `docs/sprints/current/state.yaml`
- Contracts are fully defined (no ambiguity)
- Clean git state (commit or stash any work first)

## Automation Model

```
/implement-sprint
       ↓
┌──────────────────────────────────────┐
│  AUTOMATED (no human intervention)   │
│                                      │
│  For each phase:                     │
│    1. Implement (implementer agent)  │
│    2. Run pre-commit                 │
│    3. Run tests                      │
│    4. Review (reviewer agent)        │
│    5. Run demo                       │
│    6. Analyze data (if applicable)   │
│    7. Commit phase                   │
│                                      │
│  After all phases:                   │
│    8. Run review-sprint              │
│    9. Run all demos twice            │
│   10. Run completion checks          │
└──────────────────────────────────────┘
       ↓
┌──────────────────────────────────────┐
│  PRESENT TO USER                     │
│                                      │
│  - Summary of what was built         │
│  - Test results + coverage           │
│  - Review report (issues found)      │
│  - Demo output samples (both runs)   │
└──────────────────────────────────────┘
       ↓
   User Decision
       ↓
┌─────────────┬─────────────┬──────────────────┐
│   ACCEPT    │    FIX      │     RESET        │
│             │             │                  │
│ Keep        │ Address     │ git reset to     │
│ commits     │ issues,     │ pre-sprint HEAD  │
│             │ amend/fix   │ Try again        │
└─────────────┴─────────────┴──────────────────┘
```

**Key principle:** Commit after each phase for clean git history. Reset reverts all phase commits if needed.

## Process Details

### Phase Implementation (Automated)

For each phase in the sprint:

#### Step 1: Implement

Use the **implementer** agent to write:
- Implementation code matching contracts exactly
- Tests for the phase
- Demo script

**Critical:** Follows Principle #7 (no defaults) and Principle #8 (no scaffolding) strictly.

#### Step 2: Pre-commit

```bash
pre-commit run --all-files
```

**If pre-commit fails:** Fix issues and re-run. Do not proceed until passing.

#### Step 3: Tests

```bash
# Tests with coverage
python -m pytest --cov=src/fabulexa --cov-fail-under=85

# Package installs
uv pip install -e .
```

**If tests fail:** Stop automation, report failure to user.

#### Step 4: Review

Use the **reviewer** agent to check:
- Contract compliance
- Principle #7 violations (zero tolerance)
- Principle #8 violations (no scaffolding)
- Anti-pattern detection
- Dead code (loops with pass, unused variables)

Reviewer loads minimal context (fresh eyes protocol).

**If revisions needed:** Implementer fixes, re-run gates, re-review. Limit: 3 attempts per phase.


#### Step 5: Run Demo

```bash
python docs/sprints/current/demos/phase_N_*.py
```

Demo must:
- Run without errors
- Print clear success message
- Exit with code 0

#### Step 6: Analyze Data (If Applicable)

If the demo produces simulation output, use the **data-analyst** agent to verify:
- Realistic distributions
- Appropriate inequality patterns
- No anomalies

#### Step 7: Commit Phase

Update state.yaml to show status

```bash
git add -A
git commit -m "$(cat <<'EOF'
Sprint [Name] - Phase N: [Title]

- [What this phase implemented]
- Tests: PASS
- Pre-commit: PASS

🤖 Generated with Claude Code

Co-Authored-By: Claude <noreply@anthropic.com>
EOF
)"
```

Commit message should be concise and describe what the phase delivered.

### Post-Implementation (Automated)

After all phases complete:

#### Step 8: Review Sprint

Run `/review-sprint` for comprehensive fresh-eyes audit:
- Dead code scan
- Test name audit
- Coverage analysis (100% on new files)
- Spec-implementation comparison
- Workspace check

#### Step 9: Run All Demos Twice

Run every demo script twice to verify determinism and consistency:

```bash
# First run
for demo in docs/sprints/current/demos/phase_*.py; do
    python "$demo"
done

# Second run
for demo in docs/sprints/current/demos/phase_*.py; do
    python "$demo"
done
```

Both runs must produce consistent output. Flag any differences.

#### Step 10: Completion Checks

```bash
# Final pre-commit (catch any drift)
pre-commit run --all-files

# Workspace hygiene
git status --porcelain | grep "^??"

# Scaffolding patterns
grep -rn "# Future:" src/
grep -rn "pass$" src/
```

### Present to User

Show:
1. **Summary:** What was built, files changed, lines added
2. **Tests:** Pass/fail count, coverage percentage
3. **Review report:** Issues found (blocking and non-blocking)
4. **Demos:** Sample output proving it works

### User Decision

#### ACCEPT → Keep Commits

Commits are already made per-phase. Just update state.yaml and archive sprint.

#### FIX → Address Issues

If review found issues worth fixing:
1. Fix the specific issues
2. Run pre-commit
3. Commit the fix (amend last phase commit if appropriate)
4. Re-run review-sprint
5. Present again

#### RESET → Try Again

If the sprint is too messy to salvage, reset to pre-sprint state:

```bash
# Find the commit before sprint started
git log --oneline -10

# Reset to pre-sprint commit
git reset --hard <pre-sprint-commit>
git clean -fd
```

Then run `/implement-sprint` again. Different RNG consumption may produce cleaner results.

**When to reset vs fix:**
- Few isolated issues → Fix
- Systemic problems → Reset
- "This feels wrong" → Reset (trust your gut)

## Agent Summary

| Agent | Role | When |
|-------|------|------|
| **implementer** | Write code, tests, demos | Each phase |
| **reviewer** | Check quality, find issues | After each phase |
| **data-analyst** | Verify output realism | After demos with output |

## Quality Gate Reference

| Gate | Command | Pass Criteria |
|------|---------|---------------|
| Pre-commit | `pre-commit run --all-files` | All hooks pass |
| Tests | `python -m pytest --cov=src/fabulexa` | ≥85% coverage, all pass |
| Package | `uv pip install -e .` | Installs cleanly |
| Demo | `python docs/sprints/current/demos/phase_N_*.py` | Exit 0 |

## Failure Modes

**Gate fails:**
- Report which gate, what error
- User decides: fix or reset

**Reviewer rejects 3 times:**
- Report the persistent issue
- User decides: fix manually or reset

**Demo crashes:**
- Report stack trace
- User decides: fix or reset

**Data analyst finds anomalies:**
- Report findings with data samples
- User decides: acceptable or not

## Tips

**For clean runs:**
- Ensure spec is unambiguous before starting
- Use a dedicated branch for risky sprints
- Keep sprints small (easier to reset)

**If you keep resetting:**
- The spec may be flawed (ambiguous, contradictory)
- Consider running `/plan-sprint` again
- Or manually implement the tricky part first