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):

typescript

// @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):

markdown

## 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                │
└──────────────────────────┬──────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────────┐
│  2. SELECT FOCUS                                            │
│     Choose a Context Window from Phase C                    │
└──────────────────────────┬──────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────────┐
│  3. WRITE TEST (Red)                                        │
│     Implement TEST- entry, watch it fail                    │
└──────────────────────────┬──────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────────┐
│  4. WRITE CODE (Green)                                      │
│     Implement to pass test                                  │
└──────────────────────────┬──────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────────┐
│  5. TAG CODE                                                │
│     Add // @implements ID comments                          │
└──────────────────────────┬──────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────────┐
│  6. UPDATE SoT                                              │
│     Update specs/ if implementation reveals changes         │
└──────────────────────────┬──────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────────┐
│  7. VALIDATE                                                │
│     Run tests, check traceability                           │
└──────────────────────────┬──────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────────┐
│  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:

markdown

## 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:

markdown

- **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

Bad Example:

markdown

- **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:

typescript

// @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

typescript

// @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."

Context Window Navigation

Work through Context Windows sequentially within an EPIC:

markdown

## 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)

typescript

// 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: 'test@example.com', password: 'ValidPass123!' });

    expect(response.status).toBe(201);
    expect(response.body.data.email).toBe('test@example.com');
    // Test FAILS because endpoint doesn't exist yet
  });
});

Phase 2: Green (Make Test Pass)

Write the minimum code to make the test pass:

typescript

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

Phase 3: Refactor (Improve Code Quality)

Now improve the code while tests stay green:

typescript

// @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 });
}

EPIC Phases (Detailed)

Phase A: Plan (Load Context)

Read EPIC file
Review all referenced IDs (BR-, API-, DBT-)
Check Session State section
Verify git branch is correct
Confirm dependencies are complete

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

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

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

Search AI Tools

prd-v07-implementation-loop

Install this agent skill to your Project

SKILL.md

Implementation Loop

Consumes

Produces

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

The Core Loop (The Heartbeat)

Session State Protocol (MANDATORY)

Code Traceability Protocol

Traceability Tag Patterns

Example with Full Traceability

SoT Update Rules

Context Window Navigation

Test-First Development (Red-Green-Refactor)

Phase 1: Red (Write Failing Test)

Phase 2: Green (Make Test Pass)

Phase 3: Refactor (Improve Code Quality)

EPIC Phases (Detailed)

Phase A: Plan (Load Context)

Phase B: Design (Update Specs)

Phase C: Build (Context Windows)

Phase D: Validate

Phase E: Finish (Harvest)

Red Flags (Stop and Fix)

Anti-Patterns to Avoid

Quality Gates

Downstream Connections

Detailed References