[Feature Name] — Spec

Status: Draft | Ready for implementation | In progress | Done Scope: [One sentence describing what this spec covers — what is being built or changed and why.] Reference pattern: [path/to/similar/file] ([brief description of the pattern to follow])

---

⚠️ Before you start — Generate a plan file

Before writing a single line of implementation code, generate a file called [feature-name]-plan.md in the same directory as this spec. This file must contain a sequential breakdown of every task needed to implement the spec. Each task must be atomic, ordered by dependency, and independently verifiable.

Do not proceed with implementation until this plan file exists.

Plan file structure:

# [Feature Name] — Implementation Plan

## Tasks

- [ ] 1. [Atomic task — which file, what change, what the outcome is]
- [ ] 2. [Next task — depends on task 1]
- [ ] 3. ...

## Open questions

- [Any ambiguity in the spec that must be resolved before implementing that task]

---

1. Objective

[2–4 sentences. Describe what is being replaced or built, for whom, and what the end state looks like. Be specific about correctness concerns, user context, or domain rules that motivated this work.]

---

2. Technical Context

• Stack: [e.g., Django 4.2, Python 3.11, React 18, TypeScript, library X]
• Files to read for context (do not modify):
  • path/to/file — [why it matters — e.g., contains the base class this extends, defines the interface this must match]
  • path/to/file — [what to learn from reading it]
• Files to create or modify:
  • path/to/file — [what changes here]
  • path/to/file — [what changes here]
• Files to NOT touch:
  • path/to/file — [reason it must stay unchanged]
• Follow the pattern in: path/to/reference
  • [Specific pattern rule #1]
  • [Specific pattern rule #2]
• Existing utilities to reuse:
  • UtilityName.method(args) → [what it returns / what it does]

---

3. Functional Requirements

• [What the feature does — describe the behavior, not the implementation]
• [What inputs or configuration the system accepts — list each one with type or options]
• [Any conditional logic between inputs or states]
• [Default values that matter]
• [What the output or result looks like — list each field or visible element]
• [Any user interactions or system events: create, update, delete, trigger, etc.]

---

4. Data Models — path/to/models-or-types

[Describe what to add or replace. Provide the full definition in the language/format of the stack — TypeScript interfaces, Python dataclasses, Django models, JSON schemas, DB migrations, etc.]

# Example (adapt to your stack):

class FeatureModel:
    field1: str
    field2: int
    field3: bool

---

5. Core Logic — path/to/logic

Key rules or algorithms

[Rule or operation name]:

description or pseudocode

[Rule or operation name]:

description or pseudocode

[Explain each rule briefly — what it does, edge cases, what each variable or parameter represents.]

Return value or output shape

[Describe what the function, endpoint, or process returns and what each field means.]

{
  field1: value,   // what this represents
  field2: value,   // what this represents
}

---

6. Expected Behavior (Given / When / Then)

Given [input conditions or system state]
When  [trigger — e.g., a request is made, a user action occurs, the page loads]
Then  [exact expected output or behavior, with concrete values where possible]

Given [edge case input]
When  [trigger]
Then  [expected output — e.g., returns empty list, raises validation error, shows fallback UI]

---

7. UI — path/to/component (omit if no UI changes)

Layout

┌─────────────────────────────────────┐
│ [Header area — title, actions]      │
├─────────────────────────────────────┤
│ [Main content area]                 │
│  [Element 1]      │  [Element 2]    │
│  [Element 3]                        │
├─────────────────────────────────────┤
│ [Footer area — summary, CTA]        │
└─────────────────────────────────────┘

[Component or section name]

[Describe behavior, states, and how user interactions map to system state.]

[Component or section name]

[Describe when it appears, hides, or changes, and what triggers that.]

Constraints (do NOT do in the UI)

• Do NOT [anti-pattern #1]
• Do NOT [anti-pattern #2]

---

8. Constraints (Do NOT do these)

• Do NOT install new dependencies — [existing library] is already available
• Do NOT modify path/to/protected/file
• Do NOT use [wrong approach] — use [correct approach] instead
• Do NOT apply [operation] to [wrong target] — it applies only to [correct target]

---

9. Acceptance Criteria

• [ ] [Data model includes all required fields]
• [ ] [Core logic handles the main case correctly]
• [ ] [Core logic handles edge cases: empty input, null, missing optional fields]
• [ ] [API or interface returns the expected shape]
• [ ] [Conditional behavior triggers correctly]
• [ ] [No changes to files outside the scope defined in section 2]
• [ ] [All existing tests pass]
• [ ] [No linting or type errors]

---

10. Technical Notes

• [Known bug or past mistake that this implementation must fix]
• [Intentional design decision that might look wrong but is correct — explain why]
• [Non-obvious domain rule relevant to the implementation]
• [Data shape detail — e.g., indexing convention, nullable fields, ordering assumptions]