furkangonel Technical Planning SOP
A structured process for understanding what to build, how to build it, and what could go wrong — before writing a single line of production code.
When to Use
- User wants to plan a new feature before implementing it
- User needs to design a system or subsystem from scratch
- User wants to break down a complex task into implementable steps
- User needs to make and record an architecture decision
- User is unsure where to start on a non-trivial problem
The Planning Process
1. UNDERSTAND → 2. EXPLORE → 3. DESIGN → 4. DECOMPOSE → 5. RISK
Do not skip steps. Each phase has a defined output.
Phase 1 — Understand
Goal: Nail down what "done" looks like before touching the design.
Questions to answer:
- What problem does this solve? (user story or job-to-be-done)
- Who are the users and what do they need to do?
- What are the explicit success criteria? (how do we know this is working?)
- What are the explicit constraints? (budget, timeline, stack, team size, compliance)
- What is explicitly OUT of scope?
- Is there an existing system this must integrate with?
Output template:
## Problem Statement
[One paragraph: who has this problem, what is the problem, what is the impact]
## Success Criteria
- [ ] User can do X in under Y seconds
- [ ] System handles Z requests/sec without degradation
- [ ] Error rate < 0.1% for operation W
## Constraints
- Must use existing PostgreSQL database
- Must deploy on current Kubernetes cluster
- No new external service dependencies without security review
## Out of Scope
- Admin panel (separate ticket)
- Mobile app changes (v2)
Phase 2 — Explore
Goal: Understand the existing system before proposing changes.
Actions:
- Read relevant existing code (don't rely on memory)
- Identify all call sites for code being changed
- Map data flows: where does the data come from, where does it go?
- Check for related tests — understand the existing contract
- Read any existing ADRs or design docs for context
Output: A one-paragraph "current state" summary and a list of files/modules involved.
## Current State
The user authentication flow lives in `auth/` and is called by:
- `api/routes/login.ts` (REST endpoint)
- `gateway/ws_auth.ts` (WebSocket upgrade)
- `cli/commands/login.ts` (CLI)
Session tokens are stored in Redis (`services/session_store.ts`).
Token validation happens in `middleware/auth.ts`.
## Files Involved
- `auth/` (core logic)
- `middleware/auth.ts`
- `services/session_store.ts`
- `tests/auth/` (existing test suite, ~40 tests)
Phase 3 — Design
Goal: Produce a concrete design with enough detail that implementation is unambiguous.
Design Template
## Approach
[2-3 sentences: the chosen approach and why it was chosen over alternatives]
## Data Model Changes
| Table/Schema | Change | Reason |
|---|---|---|
| `users` | Add `mfa_secret VARCHAR(64)` | Store TOTP secret |
| `sessions` | Add `mfa_verified BOOLEAN DEFAULT false` | Track MFA state |
## API Changes
| Endpoint | Method | Change |
|---|---|---|
| `/auth/login` | POST | Now returns `mfa_required: bool` |
| `/auth/mfa/verify` | POST | NEW — accepts TOTP code |
## Sequence Diagram (text)
1. Client → POST /auth/login → Server returns { token: "...", mfa_required: true }
2. Client → POST /auth/mfa/verify { code: "123456" } → Server validates TOTP
3. Server marks session as mfa_verified → Client gets final session token
## Alternatives Considered
| Option | Pros | Cons | Rejected because |
|---|---|---|---|
| SMS OTP | Familiar to users | Carrier dependency, SIM-swap risk | Security requirement |
| Email OTP | Simple implementation | Slow, email reliability | UX requirement (< 5s) |
| TOTP (chosen) | Works offline, industry standard | Requires authenticator app | — |
Architecture Decision Record (ADR) Format
For decisions that will be hard to reverse:
# ADR-042: Use PostgreSQL for job queue instead of Redis
**Status:** Accepted
**Date:** 2026-05-18
**Deciders:** @alice, @bob
## Context
We need a durable job queue for async email sending. Currently using Redis for sessions.
## Decision
Use PostgreSQL advisory locks + a `jobs` table instead of adding a Redis queue dependency.
## Consequences
- Positive: No new infrastructure dependency; jobs survive Redis restarts
- Positive: Full ACID guarantees on job state transitions
- Negative: Higher polling latency vs Redis pub/sub (acceptable: emails are not real-time)
- Negative: Slightly more complex implementation
## Rejected Alternatives
- **Redis Bull/BullMQ:** Would work but adds Redis as a hard dependency for a non-critical path
- **SQS:** Introduces AWS dependency; overkill for current volume
Phase 4 — Decompose
Goal: Break the design into tasks that a single engineer can complete in under 2 days each.
Task Breakdown Table
## Task List
| # | Task | Size | Depends on | Notes |
|---|------|------|------------|-------|
| 1 | Add DB migration: `mfa_secret`, `mfa_verified` columns | S | — | Use existing migration tool |
| 2 | Implement TOTP generation + verification (`auth/totp.ts`) | M | — | Use `otpauth` library |
| 3 | Add MFA enrollment endpoint (`POST /auth/mfa/setup`) | M | 1, 2 | Returns QR code URL |
| 4 | Update login endpoint to return `mfa_required` flag | S | 1 | Backwards-compatible |
| 5 | Add MFA verify endpoint (`POST /auth/mfa/verify`) | M | 2, 4 | Sets session mfa_verified |
| 6 | Update auth middleware to check `mfa_verified` | S | 5 | Feature-flagged |
| 7 | Unit tests for TOTP logic | S | 2 | Time-sensitive: use fixed TOTP epoch |
| 8 | Integration tests for full MFA flow | M | 3, 5, 6 | — |
Size: S = < 4h, M = 4–16h, L = > 16h (L → break it down further)
Rule: If a task is L-sized, break it into smaller subtasks before proceeding.
Phase 5 — Risk
Goal: Identify what could go wrong and decide in advance how to handle it.
## Risk Register
| Risk | Likelihood | Impact | Mitigation |
|------|-----------|--------|------------|
| TOTP clock skew causes verification failures | Medium | High | Allow ±1 time window tolerance |
| Users lock themselves out after enabling MFA | Medium | High | Add backup codes at enrollment |
| DB migration fails in production | Low | High | Test rollback script in staging first |
| Performance regression from additional auth DB queries | Low | Medium | Add index on `sessions.mfa_verified`; benchmark |
| Third-party `otpauth` library abandoned | Low | Low | Pin version; library is simple enough to vendor |
When to Stop Planning
Stop planning and start implementing when:
- You can name every file you will create or change
- Every task is S or M sized
- Success criteria are measurable
- The riskiest assumption has been tested (spike if needed)
- The design has been shared with at least one other engineer
Anti-patterns to avoid:
- Planning for > 2 days on a feature that takes < 1 week to build
- Designing in a vacuum without reading the existing code
- Creating tasks larger than L (always decompose)
- Skipping the risk register for changes to critical paths (auth, payments, data migrations)
Quick-Start Checklist
- Problem statement written in one paragraph
- Success criteria are measurable (not "it should be fast")
- Out-of-scope items explicitly listed
- Existing code explored before designing
- ADR written for irreversible decisions
- All tasks are S or M sized
- At least one mitigation per high-impact risk
- Plan reviewed by one other engineer before implementation begins