mattgierhart/prd-v07-implementation-loop

Implementation Loop

Position in workflow: v0.7 Test Planning → v0.7 Implementation Loop → v0.8 Release

Consumes

This skill requires prior work from v0.7 Epic Scoping and v0.7 Test Planning:

• EPIC-* entries (from v0.7 Epic Scoping) — EPIC context, objectives, Context & IDs table, execution plan phases, Session State tracking
• TEST-* test specifications (from v0.7 Test Planning) — Acceptance criteria in Given-When-Then format; tests define "done" for each deliverable
• API-* endpoint contracts (referenced in EPIC Context & IDs) — Implementation targets with request/response shapes, error codes, constraints
• DBT-* schema specifications (referenced in EPIC Context & IDs) — Data model, field types, relationships, constraints to implement
• BR-* business rules (referenced in EPIC Context & IDs) — Product logic constraints to enforce in code
• Existing SoT files (if brownfield) — Durable specs that guide implementation without re-research

This skill assumes EPIC- and TEST- entries are complete, with all upstream IDs fully specified.

Produces

This skill updates/creates:

• Working code (implementation of API-, DBT-, BR-, tested against TEST-) — Runnable code with @implements tags tracing back to specifications; passes all TEST- for EPIC
• Updated SoT entries (if implementation reveals changes) — When building reveals new constraints or edge cases, update API-/DBT-/BR- entries immediately (not deferred)
• Session State updates (EPIC.md Section 1) — "Brain dump" tracking exact stopping point, Next Steps for resume, blockers, decisions, Context

All implementation outputs are code and live SoT, not confidence-based. They are:

• Traceable (every function tagged with @implements pointing to specification ID)
• Tested (all TEST- for EPIC pass before marking phase/EPIC complete)
• SoT-synchronized (implementation matches specs/ or specs/ updated to match implementation reality)
• Session-state-preserved (Session State section allows seamless resume from exact stopping point)

Example code with traceability (from EPIC-01):

// @implements API-001 (POST /users)
// @see BR-001 (email uniqueness), BR-002 (password requirements), DBT-010 (users table)
export async function createUser(req: Request, res: Response) {
  // @implements BR-002 (password validation)
  const passwordResult = validatePassword(req.body.password);
  if (!passwordResult.valid) {
    return res.status(400).json({
      error: { code: 'INVALID_PASSWORD', message: passwordResult.errors[0] }
    });
  }

  // @implements BR-001 (email uniqueness check)
  const existingUser = await db.users.findByEmail(req.body.email);
  if (existingUser) {
    return res.status(409).json({
      error: { code: 'EMAIL_EXISTS', message: 'User already exists' }
    });
  }

  // @implements DBT-010 (users table creation)
  const user = await db.users.create({
    email: req.body.email,
    passwordHash: await hashPassword(req.body.password),
    createdAt: new Date(),
  });

  return res.status(201).json({ data: { id: user.id, email: user.email } });
}

Example Session State update (EPIC-01 mid-session):

## 1. Session State (The "Brain Dump")
- **Last Action**: Completed API-001–003 implementation; all tests passing. Password reset flow complete.
- **Stopping Point**: src/api/auth/reset.ts:85 — need to add rate limiting per BR-005
- **Next Steps**:
  1. Add rate limiter middleware to password reset endpoint (BR-005)
  2. Update TEST-012 to verify rate limiting (5 attempts per hour)
  3. Run full test suite for EPIC-01
  4. Move to API-005 (verify email endpoint)
- **Blockers**: None
- **Context**: Decided to implement rate limiting in middleware rather than at function level for reuse across endpoints. Using `express-rate-limit`.
- **Decisions Made**: POST /reset-password should return 429 with retry-after header when limit exceeded (API-001 error response spec). Using Redis for distributed rate limit tracking.

### Resume Instructions
> 1. Load EPIC-01 context (done in previous session)
> 2. Create new branch session if needed
> 3. Begin with Step 3 above (add rate limiter middleware)
> 4. When complete, run: `npm run test -- tests/api/auth.test.ts`
> 5. Update this Session State with new stopping point

This skill executes the build. It's the iterative cycle of: Load Context → Test → Code → Tag → Update → Validate → Repeat.

The Core Loop (The Heartbeat)

┌─────────────────────────────────────────────────────────────┐
│  1. LOAD CONTEXT                                            │
│     Read EPIC, referenced IDs, Session State                │
│     → Can you state this session's goal in one sentence     │
│       with specific IDs? If not, clarify before proceeding. │
└──────────────────────────┬──────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────────┐
│  2. SELECT FOCUS                                            │
│     Choose a Context Window from Phase C                    │
│     → Pick the smallest scope that yields a verifiable      │
│       outcome. One TEST- passing > three half-implemented.  │
└──────────────────────────┬──────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────────┐
│  3. WRITE TEST (Red)                                        │
│     Implement TEST- entry, watch it fail                    │
│     → Assertions must derive from TEST-/API-/BR- specs.     │
│       Missing detail = spec gap — flag it, don't guess.     │
└──────────────────────────┬──────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────────┐
│  4. WRITE CODE (Green)                                      │
│     Implement to pass test                                  │
│     → Minimum code to pass. No TEST- requires it? Don't     │
│       build it. No speculative features or error handling.   │
└──────────────────────────┬──────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────────┐
│  5. TAG CODE                                                │
│     Add // @implements ID comments                          │
└──────────────────────────┬──────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────────┐
│  6. UPDATE SoT                                              │
│     Update specs/ if implementation reveals changes         │
│     → Only update specs YOUR implementation changed.        │
│       Don't "improve" adjacent specs you happened to read.  │
└──────────────────────────┬──────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────────┐
│  7. VALIDATE                                                │
│     Run tests, check traceability                           │
│     → Name the specific TEST- IDs that pass. "It works"     │
│       is not validation — cite IDs.                         │
└──────────────────────────┬──────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────────┐
│  8. UPDATE SESSION STATE                                    │
│     Write to Session State before stopping                      │
└──────────────────────────┬──────────────────────────────────┘
                           │
                           └──────────► REPEAT until EPIC complete

Session State Protocol (MANDATORY)

Before ending ANY session, update the EPIC Session State section:

## 0. Session State (The "Brain Dump")
- **Last Action**: [What was just completed]
- **Stopping Point**: [Exact file:line or test failure]
- **Next Steps**: [Exact instructions for next session]
- **Context**: [Key decisions, blockers, open questions]

Good Example:

- **Last Action**: Completed API-002 (login endpoint), all tests passing
- **Stopping Point**: src/api/auth/login.ts:47 — need to add rate limiting
- **Next Steps**:
  1. Add rate limiter middleware per BR-005
  2. Update TEST-008 to verify rate limiting
  3. Move to API-003 (logout)
- **Context**: Decided to use Supabase's built-in rate limiting rather than custom middleware

Assumptions & Ambiguities: During implementation, log assumptions and ambiguities in the EPIC's structured table (see EPIC template). This makes "Think Before Coding" persistent across sessions.

Example row during implementation:

| 3 | API-001 | ASSUMPTION | Response includes created_at field | Spec says "user object" but doesn't enumerate fields | Implemented with created_at; needs spec update |

Bad Example:

- **Last Action**: Working on auth
- **Stopping Point**: Somewhere in the code
- **Next Steps**: Continue
- **Context**: N/A

Code Traceability Protocol

Every major code unit MUST declare which ID it implements:

// @implements API-001 (Create User endpoint)
// @see BR-001 (Email uniqueness)
// @see DBT-001 (Users table)
export async function createUser(data: CreateUserInput): Promise<User> {
  // Implementation...
}

Traceability Tag Patterns

| Code Element | Tag Pattern | Example | |--------------|-------------|---------| | API handler | @implements API-XXX | API endpoint function | | Business logic | @implements BR-XXX | Validation, rules | | Database model | @implements DBT-XXX | Schema definition | | UI component | @implements SCR-XXX | Screen component | | Test file | @tests TEST-XXX | Test implementation | | Cross-reference | @see [ID] | Related specification |

Example with Full Traceability

// @implements API-001 (POST /users)
// @see BR-001 (email uniqueness)
// @see BR-002 (password requirements)
// @see DBT-001 (users table)
export async function createUser(req: Request, res: Response) {
  // @implements BR-002
  const passwordResult = validatePassword(req.body.password);
  if (!passwordResult.valid) {
    return res.status(400).json({ error: passwordResult.errors });
  }

  // @implements BR-001
  const existingUser = await db.users.findByEmail(req.body.email);
  if (existingUser) {
    return res.status(409).json({ error: { code: 'EMAIL_EXISTS' } });
  }

  // @implements DBT-001
  const user = await db.users.create({
    email: req.body.email,
    passwordHash: await hashPassword(req.body.password),
  });

  return res.status(201).json({ data: user });
}

SoT Update Rules

The Source of Truth (specs/) must stay in sync with implementation:

| Situation | Action | |-----------|--------| | Spec matches implementation | No update needed | | Implementation reveals new constraint | Add BR- entry to specs/ | | API shape changed during build | Update API- entry | | New field needed in schema | Update DBT- entry | | Spec was wrong/incomplete | Fix spec AND code | | Discovered edge case | Add to spec, add TEST- |

Rule: Update specs during implementation, not "later."

Counter-rule: Only update specs that YOUR current work directly affects. If you notice that API-020 has a typo while working on API-001, log it in the Assumptions & Ambiguities table for a future session. Do not fix it now. Unplanned spec changes create invisible scope creep and break traceability for any parallel work.

Context Window Navigation

Work through Context Windows sequentially within an EPIC:

## 4. Context Windows

### Window 1: Database Schema ← CURRENT
- [x] Create users table migration
- [x] Add RLS policies
- [ ] Create sessions table
- [ ] Verify schema in studio

### Window 2: API Endpoints
- [ ] Implement API-001 (signup)
- [ ] Implement API-002 (login)
- [ ] Implement API-003 (logout)

### Window 3: UI Integration
- [ ] Build signup form
- [ ] Build login form
- [ ] Add auth state management

Test-First Development (Red-Green-Refactor)

Phase 1: Red (Write Failing Test)

// tests/api/users.test.ts
// @tests TEST-001

describe('POST /api/users', () => {
  it('creates user with valid data', async () => {
    const response = await request(app)
      .post('/api/users')
      .send({ email: '[email protected]', password: 'ValidPass123!' });

    expect(response.status).toBe(201);
    expect(response.body.data.email).toBe('[email protected]');
    // Test FAILS because endpoint doesn't exist yet
  });
});

Constraint: If the test requires details not in the TEST- spec (response field names, error codes, status codes), look them up in API-/BR- specs. Do not invent them. If the spec lacks the detail, log an AMBIGUITY in the Assumptions & Ambiguities table before proceeding.

Phase 2: Green (Make Test Pass)

Write the minimum code to make the test pass:

// @implements API-001
export async function createUser(req, res) {
  const user = await db.users.create(req.body);
  return res.status(201).json({ data: user });
}

Constraint: "Minimum code" means literally what makes this one test go green. No additional validation, no extra error handling, no service layer abstractions unless a TEST- requires that behavior. This feels uncomfortable. That is correct.

Phase 3: Refactor (Improve Code Quality)

Now improve the code while tests stay green:

// @implements API-001
// @see BR-001, BR-002
export async function createUser(req, res) {
  const validated = validateUserInput(req.body); // Add validation
  if (!validated.ok) return res.status(400).json(validated.error);

  const user = await userService.create(validated.data); // Extract service
  return res.status(201).json({ data: user });
}

Constraint: Refactor only code you just wrote. Do not "improve" existing code that was already working. Do not extract abstractions unless you have 3+ concrete uses (not hypothetical future uses). Do not touch files outside the current focus area. See references/behavioral-examples.md for detailed good/bad comparisons.

EPIC Phases (Detailed)

Phase A: Plan (Load Context)

• [ ] Read EPIC file
• [ ] Review all referenced IDs (BR-, API-, DBT-)
• [ ] Check Session State section
• [ ] Review Assumptions & Ambiguities table for unresolved items
• [ ] Verify git branch is correct
• [ ] Confirm dependencies are complete
• [ ] Can state session goal in one sentence with specific IDs

If you cannot articulate what this session accomplishes in terms of specific TEST- or API- IDs, you are not ready to build. Refine the goal until it names IDs.

Phase B: Design (Update Specs)

• [ ] Draft/refine any unclear specs
• [ ] Add missing details discovered during planning
• [ ] Create TEST- entries if not done
• [ ] Update EPIC Context & IDs section

Phase C: Build (Context Windows)

For each Context Window:

• [ ] Select focus area
• [ ] Write tests for this window
• [ ] Implement code
• [ ] Add traceability tags
• [ ] Run tests, verify passing
• [ ] Update Session State

Phase D: Validate

• [ ] All TEST- entries for this EPIC pass
• [ ] Manual verification of UJ- journeys
• [ ] @implements tags present in all major code units
• [ ] No orphaned code (everything traces to an ID)
• [ ] specs/ updated to match implementation

Phase E: Finish (Harvest)

• [ ] Move useful temp/ notes to specs/ or archive/
• [ ] Verify all specs/ files match final code
• [ ] Clean Session State section
• [ ] Update EPIC state to Complete
• [ ] Log completion in Change Log
• [ ] Commit with message: feat(EPIC-XX): [summary]

Red Flags (Stop and Fix)

| Signal | Action | |--------|--------| | Can't write test | Requirement unclear → revisit spec | | Test keeps failing | Implementation wrong OR spec wrong → investigate | | Need code outside EPIC scope | Wrong EPIC boundaries → re-scope | | Lost context mid-session | Load Session State, verify EPIC context | | Spec and code diverging | Stop, update spec to match reality | | Test is testing implementation | Rewrite to test behavior | | Writing code not required by any TEST- | Speculative — remove it, or write the TEST- first | | Editing files outside current Context Window | Scope creep — note in Assumptions & Ambiguities table, defer |

Anti-Patterns to Avoid

| Anti-Pattern | Signal | Fix | |--------------|--------|-----| | Test-after | Code written, then "add tests" | Write TEST- implementation first | | Spec drift | Code diverges from specs/ | Update SoT during implementation | | Missing traceability | Code has no @implements tags | Add tags as you write | | Session amnesia | No Session State update | ALWAYS update before stopping | | Context switching | Jumping between EPICs | Finish one EPIC before starting another | | One-shot building | No iteration, just code dump | Follow the loop: test → code → tag | | Orphaned code | Code not linked to any ID | Every function serves an ID | | Speculative error handling | try/catch for scenarios no TEST- covers | Remove it. If the scenario matters, write TEST- first. | | Drive-by improvements | "While I was here, I also improved..." | Revert non-essential changes. Note in Assumptions & Ambiguities table. | | Vague completion claims | "Auth is working" without naming IDs | Always cite IDs: "TEST-001 through TEST-005 pass. API-001, API-002 verified." |

Quality Gates

Before marking EPIC complete:

• [ ] All TEST- entries pass
• [ ] All code has @implements tags
• [ ] specs/ matches implementation
• [ ] Session State is clean
• [ ] Manual UJ- verification done
• [ ] Change Log updated

Downstream Connections

Implementation Loop outputs feed into:

| Consumer | What It Uses | Example | |----------|--------------|---------| | v0.8 Release | Completed EPICs ready for deployment | All TEST- pass, SoT current | | Code Review | @implements tags for context | Reviewer knows which BR- to check | | Future Sessions | Session State for continuity | Resume exactly where left off | | Maintenance | Traceability for debugging | "Which BR- does this code implement?" |

Detailed References

• Implementation examples: See references/examples.md
• Traceability patterns: See references/traceability.md
• Session state guide: See references/session-state.md
• Behavioral examples (good/bad): See references/behavioral-examples.md