Step 2 · Design and Technical Review

Goal

Before any code is written, produce a technical design that has been reviewed for correctness, security, performance, and maintainability. Catch design mistakes now — they are 10× cheaper to fix than implementation mistakes.

Instructions

You are in workflow step 2 of the feature-cycle. The feature spec exists. Your job is to design the technical implementation and critically review it.

Tasks to Perform

1. Read the feature spec completely

cat docs/features/FEATURE-NAME.md   # replace with actual filename
cat TODO.md

2. Design the technical approach

For each layer the feature touches, write a design:

Data Layer

  • What new tables, columns, or relationships are needed?
  • Are there schema changes? Are they backward-compatible?
  • What indexes are needed for the new query patterns?
  • Is a migration required? Is it safe to run without downtime?

Service / Business Logic Layer

  • What new classes, functions, or modules are needed?
  • Where does new logic live? Does it belong in an existing module or a new one?
  • What are the function signatures and their contracts?
  • What invariants must always hold?

API / Interface Layer

  • What new endpoints or modified endpoints?
  • What are the exact request/response shapes?
  • What HTTP status codes are returned in each case?
  • What validation rules apply?

3. Write the Technical Design Document

Add a ## Technical Design section to docs/features/FEATURE-NAME.md:

## Technical Design

### Database Changes
[Tables, columns, indexes, migrations]

### Service Layer
[New files, functions, their signatures and responsibilities]

### API Changes
[Endpoint, method, request body, responses]

### Sequence Diagram (if complex)
[Text-based: Actor → Service → DB flow]

### Error Handling
[What can go wrong, what response is produced, what is logged]

### Test Plan
[What unit tests, integration tests, edge cases to cover]

4. Security Review

Before writing code, answer these questions in the design doc:

  • [ ] Does this feature expose any user-supplied data in HTML output? (XSS risk)
  • [ ] Does this feature write to the database? Is it parameterised? (injection risk)
  • [ ] Is this feature protected by authentication? (access control)
  • [ ] Can User A access User B's data through this feature? (authorisation)
  • [ ] Does this feature accept file uploads? (path traversal, type validation)
  • [ ] Are there rate-limiting concerns? (abuse potential)

5. Performance Review

  • [ ] What is the expected query count per request?
  • [ ] Are there any N+1 patterns in the proposed design?
  • [ ] Will this feature work acceptably at 10× the current data volume?
  • [ ] Does any part of this need to be async (email, file processing, notifications)?

6. Update TODO.md

Adjust and finalise the task list based on the design:

  • Remove tasks that turned out to be unnecessary
  • Add tasks uncovered during design (migrations, edge case handlers, caching)
  • Mark any tasks that are blocked and explain why
  • Each new task must include _(ref: workflows/feature-cycle/02-design-and-review.md)_ so its origin is traceable
  • Status rules: [ ] = not started · [~] = in progress (one at a time) · [x] = done (prefix the date)

Expected Output

  • docs/features/FEATURE-NAME.md updated with ## Technical Design section
  • TODO.md refined and finalised
  • No code written yet

Exit Criteria

This step is complete when:

  • [ ] Technical design is written for every layer the feature touches
  • [ ] Security review questions are all answered (not just checked)
  • [ ] Performance implications are assessed
  • [ ] TODO.md reflects the final implementation plan
  • [ ] No open design questions remain unresolved