Step 1 · Define the Feature

Goal

Produce a complete, unambiguous feature specification before a single line of code is written.

Instructions

You are in workflow step 1 of the feature-cycle. A feature has been requested. Your job is to understand it completely and produce a written spec that a developer can execute without asking questions.

Tasks to Perform

1. Read the request context

Before writing anything, find and read:

  • The request description, issue, or ticket
  • Any existing similar features in the codebase
  • The relevant data models and API contracts
# Understand current codebase context
tree -L 3 --gitignore

# Find related existing features
grep -rn "[keyword from feature]" --include="*.{php,js,ts,py,go}" . | grep -v node_modules | grep -v vendor | head -30

# Read current routes/endpoints
grep -rn "route\|Route::\|router\." --include="*.{php,js,ts}" . | grep -v node_modules | grep -v vendor | head -30

2. Write the Feature Specification

Create docs/features/FEATURE-NAME.md with this structure:

# Feature: [Name]

## Problem Statement
[What problem does this solve? Who has the problem? How often?]

## Proposed Solution
[What will the system do? Described from the user's perspective.]

## User Stories
- As a [user type], I want to [action], so that [outcome].
- ...

## Acceptance Criteria
Each criterion is binary — pass or fail. No "should probably".

- [ ] Given [precondition], when [action], then [expected result]
- [ ] Given [precondition], when [action], then [expected result]

## Out of Scope
[Explicitly list what this feature does NOT include]

## Data Requirements
[New fields, tables, or relationships needed]

## API Changes
[New or modified endpoints, request/response shapes]

## UI Changes
[Screen descriptions, user flows — or "none" if API-only]

## Security Considerations
[Auth requirements, data access rules, sensitive data handling]

## Dependencies
[Anything that must exist before this can be built]

3. Identify risks and unknowns

Before implementation, surface:

  • Decisions that need clarification (write them in docs/features/FEATURE-NAME.md as ## Open Questions)
  • Technical risks (performance, compatibility, data migration)
  • Ambiguities in the spec

4. Write TODO.md tasks

Populate TODO.md with one task per implementation unit. Include the source reference on every entry so tasks are traceable:

## Todo
- [ ] feat: [DB migration description] _(ref: workflows/feature-cycle/01-define-feature.md)_
- [ ] feat: [Service/business logic description] _(ref: workflows/feature-cycle/01-define-feature.md)_
- [ ] feat: [API endpoint description] _(ref: workflows/feature-cycle/01-define-feature.md)_
- [ ] test: [What tests are needed] _(ref: workflows/feature-cycle/01-define-feature.md)_
- [ ] docs: [Documentation updates] _(ref: workflows/feature-cycle/01-define-feature.md)_

TODO status rules: [ ] = not started · [~] = in progress (one at a time) · [x] = done (prefix the date).

Expected Output

  • docs/features/FEATURE-NAME.md — complete spec
  • TODO.md — populated with developer-ready tasks
  • No code written yet

Exit Criteria

This step is complete when:

  • [ ] The spec covers all acceptance criteria unambiguously
  • [ ] Open questions are listed and flagged for resolution
  • [ ] TODO.md contains at least 3 actionable implementation tasks
  • [ ] Any required DB changes are identified