Technical Plans: Bridging Specification and Implementation

Introduction: The Missing Bridge

You have an approved specification scoring \geq75/100 defining WHAT to build. But there's a gap before creating executable tasks. You need to answer HOW : Which components are required? How do they interact? What database changes are needed? Which existing code do we integrate with? This is the technical plan - the bridge between specification and task decomposition.

The SDD Workflow

text ┌────────────────────────────────────────────────────────────────┐ │ 📋 PRD \to 📝 Specification (WHAT) \to 🏗️ Technical Plan (HOW) │ │ (Product Requirements Doc) ◄── CURRENT LESSON │ │ \to ✅ Task Decomposition \to 💻 Implementation 📝 │ └────────────────────────────────────────────────────────────────┘ ┌────────────────────────────────────────────────────────────────┐ │ 📋 PRD \to 📝 Specification (WHAT) \to 🏗️ Technical Plan (HOW) │ │ (Product Requirements Doc) ◄── CURRENT LESSON │ │ \to ✅ Task Decomposition \to 💻 Implementation 📝 │ └────────────────────────────────────────────────────────────────┘ SDD (Specification-Driven Development) is the workflow this course follows: starting from a PRD (Product Requirements Document), you produce a specification, then a technical plan, then decomposed tasks, and finally implementation. A technical plan translates functional requirements into concrete technical decisions. It has 7 key sections.

Reference: CODEX.md

1. Architecture (Component Interactions)

Markdown## Architecture: Task Comments Component Flow: Client → API Endpoint → CommentService → CommentRepository → Database Data Flow: 1. Client sends POST /api/tasks/{id}/comments with JWT 2. API validates token, calls `CommentService.create_comment()` 3. Service validates: user owns task, content length valid 4. Service calls CommentRepository.create() 5. Repository persists via SQLAlchemy, returns Comment 6. API transforms to CommentSchema, returns 201## Architecture: Task Comments Component Flow: Client → API Endpoint → CommentService → CommentRepository → Database Data Flow: 1. Client sends POST /api/tasks/{id}/comments with JWT 2. API validates token, calls `CommentService.create_comment()` 3. Service validates: user owns task, content length valid 4. Service calls CommentRepository.create() 5. Repository persists via SQLAlchemy, returns Comment 6. API transforms to CommentSchema, returns 201 Why: Prevents conflicting assumptions about layer responsibilities, duplicate validation, and architectural drift. Common mistakes: Reversed dependencies (Service→API), skipping layers (API→DB), ambiguous validation location. How to decide: Start from entry point → follow data transformations → identify decision points → validate against CODEX.md.

2. Data Model (Database Schema)

Markdown ## Data Model: Comment Table: comments - id: UUID, primary key, default=uuid4 - task_id: UUID, FK to tasks.id, NOT NULL - user_id: UUID, FK to users.id, NOT NULL - content: String(5000), NOT NULL - created_at: DateTime, default=utcnow, NOT NULL Relationships: - task: relationship to Task (backref="comments") - author: relationship to User (backref="comments") Indexes: - (task_id, created_at) for chronological listing ## Data Model: Comment Table: comments - id: UUID, primary key, default=uuid4 - task_id: UUID, FK to tasks.id, NOT NULL - user_id: UUID, FK to users.id, NOT NULL - content: String(5000), NOT NULL - created_at: DateTime, default=utcnow, NOT NULL Relationships: - task: relationship to Task (backref="comments") - author: relationship to User (backref="comments") Indexes: - (task_id, created_at) for chronological listing Why: Prevents N+1 queries, missing constraints, orphaned records, and performance issues. Common mistakes: No indexes, missing NOT NULL, undefined relationships, ambiguous column types. How to decide: Indexes for query patterns, NOT NULL for required data, relationships for navigation, FKs for referential integrity.

3. API Implementation (Endpoints)

Markdown## API Implementation POST /api/tasks/{task_id}/comments - Router: src/api/comments.py, async def create_comment() - Dependencies: current_user, comment_service - Response: 201 with CommentSchema - Errors: 400/401/403/404 - Error handling: Catch service exceptions → HTTPException GET /api/tasks/{task_id}/comments - Query params: skip (0), limit (50) - Response: 200 with List[CommentSchema] DELETE /api/comments/{comment_id} - Authorization: comment owner OR task owner - Response: 204 No Content## API Implementation POST /api/tasks/{task_id}/comments - Router: src/api/comments.py, async def create_comment() - Dependencies: current_user, comment_service - Response: 201 with CommentSchema - Errors: 400/401/403/404 - Error handling: Catch service exceptions → HTTPException GET /api/tasks/{task_id}/comments - Query params: skip (0), limit (50) - Response: 200 with List[CommentSchema] DELETE /api/comments/{comment_id} - Authorization: comment owner OR task owner - Response: 204 No Content Why: Prevents inconsistent error codes, missing authorization, and security vulnerabilities. Common mistakes: No error codes specified, missing authorization, unclear dependencies, ambiguous response formats. How to decide: RESTful paths, map exceptions to HTTP status, specify all dependencies, check authorization before service layer.

4. Module Structure (Files)

Markdown## Module Structure New Files: - src/models/comment.py - src/repositories/comment_repository.py - src/services/comment_service.py - src/schemas/comment.py - src/api/comments.py Test Files: - tests/unit/test_comment_{model,repository,service}.py - tests/integration/test_comment_api.py Modified Files: - src/models/task.py (add comments relationship) - src/api/__init__.py (register router) - alembic/versions/XXXX_add_comments_table.py## Module Structure New Files: - src/models/comment.py - src/repositories/comment_repository.py - src/services/comment_service.py - src/schemas/comment.py - src/api/comments.py Test Files: - tests/unit/test_comment_{model,repository,service}.py - tests/integration/test_comment_api.py Modified Files: - src/models/task.py (add comments relationship) - src/api/__init__.py (register router) - alembic/versions/XXXX_add_comments_table.py Why: Prevents files in wrong directories, forgotten tests/migrations, and merge conflicts. Common mistakes: Only listing new files, no test structure, missing migrations, incorrect paths. How to decide: Follow existing structure, one file per concern, test mirrors production, list all modifications.

5. Integration Points (Existing Code)

Markdown ## Integration Points Use Existing Code: 1. Task Model (src/models/task.py) - validate task_id, check ownership 2. User Model (src/models/user.py) - foreign key for author 3. Authentication (src/api/auth.py) - get_current_user dependency 4. Database Session (src/database.py) - get_db dependency 5. Repository Pattern (CODEX.md) - all DB access through repositories 6. Error Handling (CODEX.md) - HTTPException with status codes ## Integration Points Use Existing Code: 1. Task Model (src/models/task.py) - validate task_id, check ownership 2. User Model (src/models/user.py) - foreign key for author 3. Authentication (src/api/auth.py) - get_current_user dependency 4. Database Session (src/database.py) - get_db dependency 5. Repository Pattern (CODEX.md) - all DB access through repositories 6. Error Handling (CODEX.md) - HTTPException with status codes Why: Prevents reinventing functionality, breaking patterns, and import cycles. Common mistakes: Creating new auth, direct DB access, custom error handling, ignoring CODEX.md patterns. How to decide: Scan CODEX.md first \to review existing models \to check api/ for utilities \to validate compliance.

6. Testing Strategy (Coverage)

Markdown ## Testing Strategy Unit Tests (Mocked): - test_comment_repository.py: create, get, list, delete (95%+) - test_comment_service.py: validation, authorization logic (90%+) Integration Tests (TestClient): - test_comment_api.py: all endpoints, auth, errors (85%+) Overall Target: 90%+ ## Testing Strategy Unit Tests (Mocked): - test_comment_repository.py: create, get, list, delete (95%+) - test_comment_service.py: validation, authorization logic (90%+) Integration Tests (TestClient): - test_comment_api.py: all endpoints, auth, errors (85%+) Overall Target: 90%+ Why: Prevents inadequate coverage, untested authorization, and missing edge cases. Common mistakes: "Write some tests", no coverage targets, only unit OR integration, no error case testing. How to decide: One test file per production file, repositories 95%+, services 90%+, APIs 85%+, test authorization and validation critically. (These targets come directly from CODEX.md's Testing Standards.)

7. Security Considerations

Markdown ## Security Authorization: - Verify user owns task before comment creation - DELETE: Allow comment owner OR task owner Input Validation: - Content: 1-5000 characters - Use SQLAlchemy ORM (no raw SQL) Data Leaks: - Use Pydantic schemas for responses (never raw ORM) - Only return comments for user's tasks ## Security Authorization: - Verify user owns task before comment creation - DELETE: Allow comment owner OR task owner Input Validation: - Content: 1-5000 characters - Use SQLAlchemy ORM (no raw SQL) Data Leaks: - Use Pydantic schemas for responses (never raw ORM) - Only return comments for user's tasks Why: Prevents authorization bypasses, injection attacks, and data leaks. Common mistakes: No authorization, missing validation, raw SQL, returning ORM objects directly. How to decide: Check authorization in service layer, validate all inputs, use ORM, always use Pydantic schemas, exclude sensitive fields.

Technical Plan vs Specification

Aspect Specification Technical Plan Audience Product team + developers Developers only Focus User behavior, validation Components, files, patterns Example "Comments: 1-5000 chars" "CommentService validates, raises ValidationError"

Aspect	Specification	Technical Plan
Audience	Product team + developers	Developers only
Focus	User behavior, validation	Components, files, patterns
Example	"Comments: 1-5000 chars"	"CommentService validates, raises ValidationError"

How Detailed Should It Be?

Rule: Enough to make task decomposition obvious, but not implementation code. ❌ Too sparse: "Create comment system with FastAPI" → Can't decompose without guessing ❌ Too verbose: Full implementation code → This IS the code, not a plan ✅ Just right: "POST /api/tasks/{id}/comments, Router: src/api/comments.py, Dependencies: current_user + comment_service, Errors: 400/401/403/404" → Clear decisions, ready for tasks

Validation & Usage

Before task decomposition, validate: ✅ Follows repository pattern (API \to Service \to Repository \to DB) ✅ Uses dependency injection ✅ Uses existing models/patterns from CODEX.md ✅ All components specified ✅ Can decompose into clear tasks When to skip: Trivial changes (one field, simple bugs) Exploratory spikes Always create for: New components/tables Multi-component features Architectural changes Generating with Codex: Markdown Given approved specification (specs/task-comments/specification.md), generate technical plan for TaskMaster. Context: Review CODEX.md, analyze existing code Stack: Python 3.11, FastAPI, SQLAlchemy, PostgreSQL Required: Architecture, Data Model, API, Module Structure, Integration Points, Testing, Security Constraints: Repository pattern, DI, type hints, HTTPException Given approved specification (specs/task-comments/specification.md), generate technical plan for TaskMaster. Context: Review CODEX.md, analyze existing code Stack: Python 3.11, FastAPI, SQLAlchemy, PostgreSQL Required: Architecture, Data Model, API, Module Structure, Integration Points, Testing, Security Constraints: Repository pattern, DI, type hints, HTTPException

Summary

Technical plans bridge specification (WHAT) \to task decomposition (executable work). 7 Required sections: Architecture - Component flow and data transformations Data Model - Schemas, constraints, indexes, relationships API - Endpoints, dependencies, errors, authorization Module Structure - New/modified files, tests, migrations Integration Points - Existing code to reuse Testing - Coverage targets by layer Security - Authorization, validation, data protection Each section teaches: What to specify Why it matters Common mistakes Decision framework Right detail level: Specific enough for task decomposition but not implementation code. Always validate against CODEX.md before proceeding.