Features & Implementation

PURPOSE

Defines the mandatory feature documentation contract for every implementation in this repository.

---

REFERENCE PAGES

• QA requirements baseline: /docs/features/qa-requirements
• Auth/session example: /docs/features/31-secure-cookie-auth-session-management
• Job queue system: /docs/features/33-job-queue-system
• AdSense ads system: /docs/features/41-adsense-ads-system
• Search feature implementation: /docs/features/58-search-feature-implementation
• Referral ledger system: /docs/features/54-referral-ledger-system
• Structured notes system: /docs/features/59-structured-notes-system
• AI typing game: /docs/features/78-typing-game
• Settings + AI credits tracker: /docs/features/103-settings-ai-credits-tracker

---

CROSS-FEATURE DEPENDENCY RULES

• If a feature depends on auth state (AI usage, premium, uploads, personalization), it MUST explicitly reference FEAT-31 behavior.
• Protected page/action behavior MUST follow FEAT-31: redirect unauthenticated users to /login?next=<target>.
• Do not introduce alternate token storage or auth entry flows (no localStorage tokens, no ad-hoc modal auth fallbacks).

---

REQUIRED FILE LOCATION

• Every feature MUST be documented in docs/features/<issue-id>-<slug>.md
• Example: docs/features/FEAT-142-user-login.md
• The file MUST be created when the feature work starts
• The same file MUST be updated whenever API behavior, UI behavior, logic, or edge cases change

---

REQUIRED DOCUMENT STRUCTURE

Every feature doc MUST use this exact structure:

# Feature: <Feature Name>

## Metadata

• - Issue ID: <FEAT-XXX>
• - Status: In Progress | Done
• - Owner: <agent/dev>
• - Related PRs: <links>

---

## Overview

Short, factual explanation of what the feature does.

---

## Frontend Behavior

• UI states
• User interactions
• Validation rules
• Error handling

---

## Backend Behavior

• Endpoints
• Request/response formats
• Business logic
• Failure modes

---

## QA Test Scenarios

---

## Edge Cases

• Empty states
• Network failures
• Race conditions
• Authorization issues

---

## Notes

• Feature flags
• Dependencies
• Known limitations

---

QA SCENARIO RULES

• MUST include at least 1 happy-path scenario
• MUST include at least 2 validation or error scenarios
• MUST include at least 1 backend failure scenario
• MUST include at least 1 edge-case scenario
• MUST use scenario IDs in the format <ISSUE-ID>-XX
• MUST write concrete steps and expected results; vague entries such as test login are forbidden
• Security-sensitive features (auth, sessions, billing, premium, AI gating) MUST include: unauthorized access test, expiry/refresh test, logout/revocation test, and abuse/rate-limit test

---

IMPLEMENTATION COVERAGE RULES

• Frontend changes MUST document UI states, user interactions, validation, and failure UI
• Backend changes MUST document invalid inputs, failure modes, timeouts, and authorization behavior
• Do NOT document only success cases
• Do NOT defer documentation until after implementation; the file must evolve with the code

---

PR ENFORCEMENT

A PR is INVALID unless:

• The feature doc exists
• The QA scenarios table is complete
• Scenario IDs are present
• The doc matches the actual implementation

PR checklist:

• Feature doc created/updated
• QA scenarios added
• Edge cases documented

---

ANTI-PATTERNS

• MUST NOT skip documentation
• MUST NOT store QA only in the issue tracker
• MUST NOT merge without documented edge cases
• MUST NOT create duplicate feature docs in multiple locations