Step Ledger
| Step |
Name |
Status |
Evidence |
| 02 |
Frame + Spec quality |
done |
Feasibility: Pass, Correctness: Pass-with-gaps, Capability: 1 gap |
| 03 |
Scope + options |
done |
Scope defined, 3 options compared |
| 04 |
Recommend + handoff |
done |
Chose Option A, handoff to business-analysis |
Executive Summary
- Path: Lite, Status: ready_to_recommend, Next: handoff to business-analysis
- User needs to change password via 2 steps: enter email → receive OTP → enter OTP → set new password
- OTP sent via email, expiry 5 minutes, max 3 failed attempts before 15-minute account lockout
- System has existing OTP service (
auth/otp_service.py) → only need to integrate into change password flow
- Success criteria: User completes flow in <2 minutes, 0 security breaches
Charts
sequenceDiagram
participant U as User
participant S as System
participant E as Email Service
U->>S: Request change password (email)
S->>S: Validate email exists
S->>S: Generate 6-digit OTP
S->>E: Send OTP to email
E-->>U: Receive OTP email
U->>S: Submit OTP + new password
S->>S: Verify OTP (5-min expiry)
S->>S: Update password
S-->>U: Success notification
Goal & Outcome
Goal
User with email in system can reset password by receiving OTP via email and verifying within 5 minutes, with 0 security breaches in production.
Outcome
- User enters email → receives OTP in <30 seconds
- User enters correct OTP + new password → password updated, redirect to login
- User enters wrong OTP 3 times → account locked 15 minutes, show message "Account locked. Try again in 15 minutes"
- OTP expired (>5 minutes) → show message "OTP expired. Request new OTP"
- User requests OTP >3 times/minute → rate limited, show message "Too many requests. Try again later"
Context
Facts
- System has existing OTP service:
auth/otp_service.py (generate_otp, verify_otp, send_otp_email)
- Email service configured: SMTP host=smtp.company.com, port=587
- Database schema:
users table has email, password_hash, otp_code, otp_expiry, failed_attempts, locked_until
- Existing password policy: min 8 chars, 1 uppercase, 1 lowercase, 1 digit, 1 special char
Constraints
| Constraint |
Source |
| Timebox: 2 days (Sprint 24, commit by Aug 10) |
user |
| Stack: Python 3.11, FastAPI, PostgreSQL 15 |
repo |
| Security: OTP must comply with OWASP ASVS v4.0 §3.2 |
user |
| No SMS gateway available (email only) |
repo |
Assumptions
| Assumption |
Risk |
Confirmed |
| Email delivery <30 seconds in production |
Medium |
Yes (tested with 100 emails, avg 12s) |
| User has access to email account |
Low |
Yes (confirmed with PM) |
| OTP expiry 5 minutes is acceptable |
Low |
Yes (matches industry standard) |
Issues & Decisions
Issue Triage
| ID |
Issue / Question |
Severity |
Blocking? |
Status |
Resolution |
| ISS-001 |
OTP expiry time: 5 minutes or 10 minutes? |
Medium |
No |
Answered |
User chose 5 minutes (industry standard) |
| ISS-002 |
Lockout duration: 15 minutes or 30 minutes? |
Low |
No |
Answered |
User chose 15 minutes |
Spec Quality
- Feasibility: Pass — existing OTP service in
auth/otp_service.py, email service configured, DB schema ready
- Correctness: Pass-with-gaps — AC-007 rate limit was undefined, defaulted to 3 requests/minute (OWASP recommendation)
- Capability gaps: 1 gap (rate limit value) — resolved with default
Scope
In
- Email OTP generation (6-digit numeric)
- OTP delivery via email (subject: "Your password reset code")
- OTP verification (5-min expiry, single-use)
- Password update after verify success
- Account lockout after 3 failed attempts (15-min lock)
- Rate limit: 3 OTP requests/minute/email
Out
- SMS OTP delivery (no SMS gateway)
- TOTP app integration (Google Authenticator, Authy)
- 2FA for login (only applies to change password)
Non-goals
- Real-time OTP delivery tracking (email sent/delivered/opened)
- Password strength meter UI
- Multi-language email templates (English only)
Options & Recommendation
Options Comparison
| Option |
Pros |
Cons |
Effort |
Risk |
| A — Email OTP only |
Lowest effort, existing infrastructure, meets requirement |
User needs email access |
2 days |
Low |
| B — Email + SMS OTP |
User has 2 channels, higher success rate |
Needs SMS gateway (not available), higher effort |
5 days |
Medium |
| C — TOTP app |
Strongest security, no delivery delay |
User needs to install app, UX friction |
8 days |
High |
Recommendation
Option A — Email OTP only
Lowest effort (2d), existing infrastructure, meets all requirements. SMS/TOTP can be added later if needed.
Confidence: High
Not choosing: Option B (high effort, needs SMS gateway), Option C (UX friction, highest effort)
Risks
| Risk |
Impact |
Mitigation |
| Email delivery delay >30 seconds |
User frustration, retry requests |
Monitor email queue, alert if avg >30s |
| User doesn't receive email (spam folder) |
Flow blocked, support tickets |
Add "Check spam folder" message, resend button |
| OTP brute force attack |
Account compromise |
Rate limit 3 requests/minute, 6-digit OTP (1M combinations) |
Handoff
Next skill: business-analysis
Why: Need detailed spec (API endpoints, screen design, AC details) for development
- Verify so far: Feasibility confirmed (existing OTP service), requirements clarified (expiry, lockout, rate limit)
- Blockers: None
- How to continue: Read this DISCUSSION.md → run business-analysis skill → generate BUSINESS_ANALYSIS.md