Spider.md - Keep the Trace, Not the Transcript

# Spider.md - SP(IDE)R Methodology
<!-- Specification, Pseudocode, Implementation, Debugging, Evaluation, Review -->
<!-- A structured approach to AI-assisted development with full traceability -->
<!-- Last updated: 2026-07-27 -->

## What is SP(IDE)R?

**SP(IDE)R** stands for **S**pecification, **P**seudocode, **I**mplementation, **D**ebugging, **E**valuation, **R**eview - a six-phase working methodology for turning requirements into production code with AI assistance. Each phase produces artifacts that feed the next, creating a complete trail from "what do we need?" to "is it working correctly, and how do we know?"

This is a methodology to adapt, not a standard to certify against. Teams that use it report that the artifacts pay for themselves the first time someone has to explain a change months later. Take the parts that fit your work and drop the rest - a spec you actually write beats a template you abandon.

### Why SP(IDE)R?

The failure mode it exists to prevent: jumping straight to "build me this feature." That works for small tasks and falls apart on complex ones, because

1. the assistant lacks context about constraints, trade-offs, and existing patterns,
2. generated code misses edge cases that become production bugs,
3. there is no record of why the code came out this way, and
4. debugging code is much harder when you never understood the approach.

SP(IDE)R fixes this by making each phase explicit and each phase's output reviewable. You and the assistant think through the problem together before a line of code exists.

### The Six Phases

```mermaid
flowchart LR
    S["S - Specification<br/>WHAT and WHY"] --> P["P - Pseudocode<br/>HOW, at a high level"]
    P --> I["I - Implementation<br/>the code, and the trace<br/>of how it was produced"]
    I --> D["D - Debugging<br/>find and fix, systematically"]
    D --> E["E - Evaluation<br/>verify against the spec"]
    E --> R["R - Review<br/>quality, independently assessed"]
    D -.->|new constraint discovered| S
    E -.->|requirement not met| P
```

The dotted edges matter as much as the solid ones. Discovering a missing constraint in Debugging means the spec was wrong, and the fix belongs in the spec.

## Phase 1: Specification

### Example: Adding Team Billing to a SaaS Platform

```markdown
# SPEC: Team Billing Feature
Date: 2026-07-27
Author: Sarah Chen
Status: Approved

## Problem Statement
Currently, each user has an individual subscription. Customers with 5+ users
are asking for team billing so one person can manage payment for the group.
We are losing deals to competitors who offer this. Sales reports 12 lost
deals last quarter totaling USD 86K ARR due to missing team billing.

## Requirements

### Functional
1. A user can create a "team" and invite members by email
2. The team owner manages billing for all members
3. Members do not see billing details - only the owner and billing admins
4. Team pricing: USD 15/seat/month (vs USD 20/month individual), minimum 5 seats
5. Adding a member mid-cycle prorates the charge
6. Removing a member does not issue a refund but reduces the next invoice
7. The owner can designate up to 2 "billing admins" who manage payment methods

### Non-Functional
- Billing changes must be reflected within 60 seconds (near-real-time)
- All billing events must be logged for audit (SOC 2 requirement)
- Must integrate with existing Stripe subscription infrastructure
- Must not break individual user billing (backward compatible)

### Out of Scope (for this iteration)
- Team hierarchy (nested teams)
- Usage-based billing per team
- Team-level feature flags (all members get the same plan)

## Constraints
- Stripe API - we use Stripe Subscriptions with metered billing
- Database: PostgreSQL - needs a migration for the new tables
- Auth: Must respect the existing role-based access control (RBAC)
- Do not modify packages/legacy-billing/ - frozen pending decommission
- Timeline: Must ship by the end of Sprint 48 (4 weeks)

## Success Criteria
- 10 teams created within the first month of launch
- 0 billing errors in the first 30 days
- No regression in individual billing flows

## Verification Criteria
- pnpm test:unit packages/billing - all green, 90% coverage on new code
- pnpm test:integration billing - includes the Stripe test-mode webhook suite
- Manual: create team, add member mid-cycle, confirm the prorated line item
  in the Stripe dashboard matches the invoice preview
- Human sign-off required: anything touching invoice calculation

## Autonomy
- Agent may implement: schema, service layer, tests, API handlers
- Human approval required before merge: the migration, and any file under
  packages/billing/stripe/
```

### Specification Template

```markdown
# SPEC: [Feature Name]
Date: YYYY-MM-DD
Author: [Name]
Status: [Draft | In Review | Approved | Superseded by SPEC-nnn]

## Problem Statement
[What problem does this solve? Who is affected? What is the business impact?]

## Requirements

### Functional
1. [Requirement with measurable acceptance criteria]
2. [Another requirement]

### Non-Functional
- [Performance, security, scalability, compliance requirements]

### Out of Scope
- [Explicitly list what this feature does NOT include]

## Constraints
[Technical, business, timeline, and resource constraints. Name the files and
modules that must not change - scope boundaries are the constraint an agent
is most likely to violate.]

## Success Criteria
[How do we know this feature is successful? Measurable outcomes.]

## Verification Criteria
[The exact commands that prove the change is correct, plus anything a human
must check by hand. If you cannot fill this in, the spec is not finished.]

## Autonomy
[What may be implemented without approval, and what requires a named human
before merge.]

## Open Questions
- [ ] [Question that needs answering before implementation]
- [ ] [Another open question]
```

## Phase 2: Pseudocode

### Example: Team Billing Pseudocode

```markdown
# PSEUDOCODE: Team Billing Feature
Spec: SPEC-team-billing
Date: 2026-07-27

## Data Model Changes

New tables:
  teams
    - id (UUID, PK)
    - name (varchar)
    - owner_id (FK -> users.id)
    - stripe_subscription_id (varchar, nullable)
    - seat_count (integer, default 5)
    - created_at, updated_at

  team_members
    - id (UUID, PK)
    - team_id (FK -> teams.id)
    - user_id (FK -> users.id)
    - role (enum: owner, billing_admin, member)
    - joined_at
    - UNIQUE(team_id, user_id)

  team_billing_events
    - id (UUID, PK)
    - team_id (FK -> teams.id)
    - event_type (enum: member_added, member_removed, plan_changed, payment_failed)
    - actor_id (FK -> users.id)
    - actor_kind (enum: human, agent, system)
    - metadata (jsonb)
    - created_at

## Core Flows

### Create Team
1. Validate: user does not already own a team
2. Create team record with owner
3. Add owner as team_member with role=owner
4. Create Stripe subscription with quantity=5 (minimum seats)
5. Migrate owner's individual subscription to team (cancel individual, activate team)
6. Log billing event: team_created

### Add Member
1. Validate: actor is owner or billing_admin
2. Validate: invited email is not already on this team
3. Validate: team has available seats (or auto-increase seat count)
4. Send invitation email
5. On acceptance:
   a. Create team_member record
   b. Update Stripe subscription quantity
   c. Prorate charge for the remaining billing period
   d. Cancel the member's individual subscription (if they had one)
   e. Log billing event: member_added

### Remove Member
1. Validate: actor is owner or billing_admin
2. Validate: cannot remove the owner (must transfer ownership first)
3. Soft-delete team_member record (set removed_at)
4. Decrease Stripe subscription quantity (effective next billing cycle)
5. User reverts to free tier (no automatic individual subscription)
6. Log billing event: member_removed

## Edge Cases
- User invited to a team but already has an annual individual plan
  -> Prorate refund on the individual plan, then add to the team
- Team owner's payment method fails
  -> 3-day grace period, then downgrade all members to free tier
- Last billing admin removed
  -> Ownership reverts to the team owner automatically
- Team reduced below 5 seats
  -> Keep billing at the 5-seat minimum, show a warning
```

### Pseudocode Template

```markdown
# PSEUDOCODE: [Feature Name]
Spec: [Link to specification]
Date: YYYY-MM-DD

## Data Model Changes
[New tables, columns, indexes, or schema modifications]

## Core Flows
[Step-by-step logic for each major operation]

## Edge Cases
[List edge cases and how each is handled]

## Integration Points
[External APIs, services, or systems this feature touches]

## Error Handling
[How each type of failure is handled]
```

## Phase 3: Implementation

### Record the run, not the chat

An older version of this template logged implementation as a conversation: prompt, response, edits. That shape no longer describes the work. An agent now plans, edits across many files, runs commands, reads the output, and iterates - often for many minutes without a human turn. There is no single prompt-and-response pair to paste.

What is worth capturing is the **run trace**: a plan, the actions actually taken, the verification that was run, and what a human changed afterwards.

Why bother:

- **It is the audit artifact.** It is the only record of how a change came to exist. Diffs show what changed; the trace shows why those files and not others.
- **It is the diagnostic.** Six months later, when a change turns out to be wrong, the trace tells you whether the plan was wrong, the plan was right and the execution drifted, or the verification never covered the case.
- **It is where governance now lives.** Review used to mean inspecting an artifact before it was applied. Agents apply things - they write files, run migrations, call APIs. So control has moved from reviewing an artifact to constraining an action: what the agent may touch, what it must ask about, and what it must prove before finishing. The trace is the evidence that those constraints held.

Keep one run record per agent run in `docs/traces/`, and link it from the pull request.

### Example: Agent Run Record

```markdown
# RUN: Team Billing - database schema and service layer
Pseudocode: PSEUDO-team-billing
Date: 2026-07-27
Human owner: Sarah Chen
Agent: repo coding agent (tool and model recorded in .agent-runs/)
Duration: 38 minutes wall clock, 4 human interventions

## Goal
Land the three new tables and the TeamBillingService create/add/remove paths,
with unit tests. Migration file generated but NOT applied to any shared database.

## Plan the agent committed to before acting
1. Read prisma/schema.prisma and packages/billing/ for existing patterns
2. Add Team, TeamMember, TeamBillingEvent models following those patterns
3. Generate the migration, do not run it against staging
4. Implement TeamBillingService with the three flows from the pseudocode
5. Unit tests for each flow plus the four edge cases
6. Run pnpm lint, pnpm typecheck, pnpm test:unit packages/billing

## Actions taken
Files created:
- packages/billing/src/team-billing.service.ts
- packages/billing/src/team-billing.service.test.ts
- prisma/migrations/<generated-timestamp>_add_team_billing/migration.sql

Files modified:
- prisma/schema.prisma (3 models added)
- packages/billing/src/index.ts (export added)

Commands run:
- pnpm prisma migrate dev --create-only --name add_team_billing
- pnpm lint            -> 0 errors
- pnpm typecheck       -> 0 errors
- pnpm test:unit packages/billing -> 31 passed, 0 failed
- pnpm test:unit packages/billing --coverage -> 93% on changed files

Scope boundary respected: no files under packages/legacy-billing/ were read
or written.

## Deviations from the plan
- Step 2: the pseudocode said seat_count defaults to 5. The agent set it
  nullable instead and flagged the conflict rather than choosing silently.
  Human decided: nullable, set explicitly at creation. Pseudocode corrected.
- Step 5: the agent could not write a meaningful test for the annual-plan
  proration edge case without a Stripe fixture, and said so instead of
  writing a test that asserted nothing. Tracked as a follow-up.

## Verification result
All automated gates green (see Commands run). Coverage gate met.
NOT verified by this run: proration math against real Stripe behavior,
because that needs the integration suite and Stripe test-mode keys.

## Human changes after the run
1. Added cascade delete on team_members when a team is deleted - the agent
   had left it as RESTRICT, which would have blocked team deletion entirely
2. Renamed TeamBillingService.addSeat to addMember for consistency with the spec
3. Rewrote two test names that described the implementation, not the behavior

## Approval
Reviewed and approved by: Sarah Chen
Migration reviewed separately by: Marcus Webb (required - schema change)
```

### Agent Run Record Template

```markdown
# RUN: [What this run was supposed to accomplish]
Pseudocode: [Link]
Date: YYYY-MM-DD
Human owner: [Name - the person accountable for this run]
Agent: [Tool and model, recorded exactly as invoked]
Duration: [Wall clock, and how many times a human intervened]

## Goal
[One paragraph. What "done" means for this run specifically.]

## Plan the agent committed to before acting
[The plan as stated up front. Capture it BEFORE execution - a plan
reconstructed afterwards is a summary, not a commitment, and it cannot
tell you whether execution drifted.]

## Actions taken
Files created / modified / deleted: [full paths]
Commands run: [exact command and its result]
External calls made: [APIs, services, anything outside the repository]
Scope boundaries: [confirm the off-limits paths were not touched]

## Deviations from the plan
[Every place the run departed from the plan, and why. This is the highest
value section in the record.]

## Verification result
[Which gates ran, what they returned, and what was NOT verified.]

## Human changes after the run
[Numbered. What a person had to fix tells you where the agent is weak,
and that is how you improve the spec next time.]

## Approval
Reviewed and approved by: [Named human]
[Separate approvals for migrations, auth, billing, or data deletion]
```

### Working rules for this phase

1. **Scope each run to something reviewable.** A run that touches 40 files across 5 modules cannot be meaningfully reviewed, and its trace will not help you either. Split it.
2. **Capture the plan before execution starts.** A plan written after the fact is a narrative.
3. **Never let a run apply an irreversible action unsupervised** - migrations against shared databases, production deploys, destructive data operations, credential changes.
4. **Record what was not verified.** Silence about coverage reads as coverage.
5. **Treat a deviation as a spec defect first.** If the agent had to depart from the plan, the plan was probably incomplete.

## Phase 4: Debugging

Keep the hypothesis discipline. It is the part of debugging that agents are worst at on their own - they are strongly inclined to try a fix immediately, and a fix applied before the cause is known is how a one-line bug becomes a three-file mess.

### Debugging Session Template

```markdown
# DEBUG: [Issue Title]
Date: YYYY-MM-DD
Severity: [P0-Critical | P1-High | P2-Medium | P3-Low]
Feature: [Related feature/spec]
Investigated by: [Name, agent, or both - name who did which part]

## Symptoms
[What is happening? Include exact error messages, screenshots, logs]

## Reproduction Steps
1. [Step-by-step to reproduce]
2. [Be specific about data, state, and timing]

## Investigation

### Hypothesis 1: [Description]
Evidence for: [What supports this theory]
Evidence against: [What contradicts it]
Test: [The exact command or query that confirms or rejects it]
Result: [Confirmed/Rejected]

### Hypothesis 2: [Description]
Evidence for: [What supports this theory]
Test: [The exact command or query that confirms or rejects it]
Result: [Confirmed - this was the root cause]

## Investigation trace
[If an agent did the investigation, record what it actually ran: the log
queries, the commands, the files it read. A conclusion with no trace is an
assertion. Note anything it changed while investigating - an agent that
edits code mid-diagnosis has contaminated the reproduction.]

## Root Cause
[Detailed explanation of what went wrong and why]

## Fix
[Description of the fix, with file paths and code changes]

## Verification
[How the fix was verified - the failing test that now passes, and the
command that runs it. "Seems fine now" is not verification.]

## Prevention
[What stops this class of bug next time? A linting rule, a test, a type,
a constraint in the spec, or a narrower scope boundary for agent runs.]
```

### Rules for agent-assisted debugging

1. **Reproduce before hypothesizing, hypothesize before fixing.** State the hypothesis and the test that would reject it, in that order.
2. **Investigation is read-only until the cause is confirmed.** An agent that has been silently editing files while investigating has destroyed the reproduction.
3. **Reject a fix that has no failing test behind it.** The test that failed before and passes after is the whole proof.
4. **A fix that touches more files than the bug is a refactor.** Separate them.

## Phase 5: Evaluation

### Evaluation Checklist

```markdown
# EVALUATION: [Feature Name]
Spec: [Link to specification]
Date: YYYY-MM-DD
Evaluator: [Name - a human, and not the person who wrote the code]

## Specification Compliance
- [ ] Requirement 1: [Met/Not Met/Partially Met] - [Notes]
- [ ] Requirement 2: [Met/Not Met/Partially Met] - [Notes]
- [ ] Requirement 3: [Met/Not Met/Partially Met] - [Notes]

## Verification Criteria from the Spec
- [ ] Every command listed in the spec was run, with its output recorded
- [ ] Anything the spec marked for manual checking was checked by a human
- [ ] Anything NOT verified is listed explicitly, with the reason

## Test Coverage
- Unit tests: [X]% coverage on new code
- Integration tests: [List of integration test scenarios]
- E2E tests: [List of end-to-end test scenarios]
- Edge cases tested: [List from the pseudocode edge cases]

## Performance
- [Metric 1]: [Measured value] vs [Target value]
- [Metric 2]: [Measured value] vs [Target value]

## Security Review
- [ ] Input validation on all user-facing endpoints
- [ ] Authorization checks on all team operations
- [ ] No PII in logs
- [ ] Stripe webhook signature verification
- [ ] No secret, token, or credential added to a file an agent reads

## Accessibility
- [ ] Keyboard navigation works for all new UI elements
- [ ] Screen reader compatibility verified
- [ ] Color contrast meets WCAG AA standards

## Provenance
- [ ] Every agent run is linked from the pull request
- [ ] Every run record names a human owner and an approver
- [ ] Human sign-off obtained for every item the spec marked as requiring it

## Deployment Readiness
- [ ] Database migration tested on a staging data copy
- [ ] Feature flag in place for gradual rollout
- [ ] Rollback plan documented
- [ ] Monitoring and alerts configured
- [ ] Runbook updated with the new operational procedures
```

## Phase 6: Review

### The self-review anti-pattern

The tempting setup is one agent that writes the change, reviews it, fixes what it found, and marks it approved. Do not build this. It fails in two specific ways:

- **Inherited blind spots.** The reviewer is working from the same plan and the same assumptions that produced the code. Whatever the plan failed to consider, the review also fails to consider. A misread requirement gets confirmed rather than caught.
- **Findings that vanish.** When the same process can both raise a finding and edit the code, a finding can be silently resolved before any human sees that it existed. You lose the signal that the change needed fixing at all, which is exactly the signal that tells you where your specs are weak.

The pattern that works:

1. **Independent reviewers.** A review pass that did not produce the code, that reads the diff and the spec rather than inheriting the author's plan.
2. **Narrow scope per reviewer.** One pass for security, one for the spec compliance, one for test quality. A reviewer asked to find everything reliably finds the shallow things.
3. **Immutable findings.** Reviewers emit findings; they do not edit code. A finding is written down, then addressed in a separate, attributed change.
4. **A named human approves.** Automated review is a filter that raises the floor. It is not the approval.

The point is not that agents review badly. It is that a reviewer who can rewrite the evidence is not a reviewer.

### Review Session Template

```markdown
# REVIEW: [Feature Name]
Date: YYYY-MM-DD
Reviewers: [Names, and any automated review passes, listed separately]
Outcome: [Approved | Approved with Changes | Needs Rework]
Approved by: [Named human - required, cannot be an agent]

## Inputs Read
- [ ] Specification
- [ ] Pseudocode
- [ ] Agent run records for every run that contributed to this change
- [ ] The diff

## Code Quality Assessment
- Readability: [1-5] - [Notes]
- Maintainability: [1-5] - [Notes]
- Test quality: [1-5] - [Notes]
- Error handling: [1-5] - [Notes]

## Architecture Fit
- Does this follow existing patterns? [Yes/No - details]
- Are there any new patterns introduced? [If yes, are they justified?]
- Technical debt introduced: [None/Acceptable/Needs cleanup ticket]

## Findings
| ID | Raised by | Severity | Finding | Resolution | Resolved by |
|----|-----------|----------|---------|------------|-------------|
| F-1 | [Human or review pass] | [blocker/concern/nit] | [What] | [How] | [Who] |

[Findings are recorded even when they are fixed immediately. A finding that
was raised and silently resolved teaches you nothing.]

## Knowledge Transfer
- Documentation updated: [Yes/No]
- Team walkthrough completed: [Yes/No]
- On-call runbook updated: [Yes/No]

## Action Items
- [ ] [Action item 1] - Owner: [Name] - Due: [Date]
- [ ] [Action item 2] - Owner: [Name] - Due: [Date]

## Lessons Learned
- [What went well in this implementation?]
- [What would we do differently next time?]
- [What should we add to our coding standards, AGENTS.md, or CLAUDE.md?
  A rule added here is a rule every future agent run inherits, so this
  question is worth real thought - it is how the team compounds.]
```

## Decision Log

### Tracking Decisions Across Phases

Every decision carries who made it. Once agents propose decisions as well as implement them, "a person concluded this" and "a person accepted a proposal" are different facts, and the difference is what you will want later.

| ID | Phase | Date | Decision | Rationale | Alternatives Considered | Decided by |
|----|-------|------|----------|-----------|------------------------|------------|
| D-001 | Spec | 2026-07-27 | Minimum 5 seats for team billing | Aligns with the target customer segment (5+ users), simplifies pricing | 3-seat minimum, no minimum | human (Sarah Chen) |
| D-002 | Pseudo | 2026-07-27 | Use Stripe Subscriptions, not Invoices | Handles proration automatically, matches existing billing code | Manual invoice generation | human (Sarah Chen) |
| D-003 | Impl | 2026-07-27 | Wrap team creation in a Prisma transaction | Atomic - if Stripe fails, the team record rolls back | Saga pattern (over-engineered) | agent-with-human-review (Sarah Chen) |
| D-004 | Impl | 2026-07-27 | seat_count nullable, set at creation | Agent flagged a conflict with the pseudocode rather than choosing silently | Default of 5 | human (Sarah Chen) |
| D-005 | Debug | 2026-07-27 | Grace period is 3 days, not 7 | Reduces revenue leakage, matches industry practice | 7 days, immediate downgrade | human (Marcus Webb) |
| [ID] | [Phase] | [Date] | [What was decided] | [Why] | [What else was considered] | [human / agent / agent-with-human-review] |

## Best Practices

1. **Do not skip phases** - Even for small features, write at least a brief spec and pseudocode. The 15 minutes you invest saves hours of rework.
2. **Use AI in every phase** - Not just implementation. Have it review the spec for gaps, attack the pseudocode for missing edge cases, and draft the evaluation checklist. It is often a better critic than author.
3. **Scope each run to something a person can review** - If the trace is too long to read, the change was too large to land in one piece.
4. **Record deviations** - Every place the implementation departs from the pseudocode, and why. This is the most valuable knowledge in the whole set for whoever comes next.
5. **Review with the full chain** - The reviewer reads the spec and pseudocode before the diff. Context makes reviews faster and much better.
6. **Never approve your own work, and do not let an agent approve its own either** - Independent review, immutable findings, a named human on the approval line.
7. **Feed lessons back into the context files** - A rule added to `AGENTS.md` or `CLAUDE.md` applies to every future run. That is how the methodology compounds instead of merely documenting.
8. **Archive completed sessions** - Move finished specs, run records, and reviews to a `completed/` directory. They become searchable precedent for the next similar feature.