Feature Management¶

Features are the core tracking unit in Klondike. They represent discrete units of work with clear acceptance criteria that can be verified.

The Feature Lifecycle¶

stateDiagram-v2
    [*] --> NotStarted: feature add
    NotStarted --> InProgress: feature start
    InProgress --> Verified: feature verify
    InProgress --> Blocked: feature block
    Blocked --> InProgress: feature start
    Verified --> [*]

Adding Features¶

Create a new feature with description, category, and acceptance criteria:

klondike feature add "User can reset password via email" \
  --category core \
  --priority 2 \
  --criteria "Reset link sent,Link expires in 24h,Password updated on submit"

Feature Options¶

Option	Description	Example
`--category`	Feature category	`core`, `ui`, `api`, `docs`
`--priority`	Priority level 1-5	`1` (critical) to `5` (future)
`--criteria`	Acceptance criteria (comma-separated)	`"Criterion 1,Criterion 2"`

Priority Levels¶

Priority	Meaning	When to Use
P1	Critical	Blocks everything else
P2	High	Needed for MVP
P3	Medium	Enhances experience
P4	Low	Nice to have
P5	Future	After MVP

Categories¶

Common categories include:

core - Core functionality
ui - User interface
api - API endpoints
infrastructure - Setup, CI/CD, tooling
docs - Documentation
testing - Test coverage
security - Security features
performance - Optimization

Listing Features¶

View all features:

klondike feature list

Filter by status:

klondike feature list --status not-started
klondike feature list --status in-progress
klondike feature list --status verified

Get JSON output for scripting:

klondike feature list --json

Starting Work¶

Mark a feature as in-progress:

klondike feature start F001

One Feature at a Time

Focus on one feature at a time. Starting a feature helps track what's actively being worked on across sessions.

Viewing Feature Details¶

See full details for a feature:

klondike feature show F001

This displays:

Description
Category and priority
Status
Acceptance criteria
Any notes or evidence

Editing Features¶

Update a feature's metadata or add notes:

# Add notes
klondike feature edit F001 --notes "Consider using OAuth instead"

# Add more acceptance criteria
klondike feature edit F001 --add-criteria "Support Google OAuth"

Verifying Features¶

When a feature is complete, verify it with evidence:

klondike feature verify F001 --evidence "tests/password-reset.test.js"

Evidence Required

You must provide evidence when verifying a feature. This prevents premature "victory declaration" where features appear done but haven't been properly tested.

Good evidence includes:

Test file paths
Screenshot locations
API response examples
Manual test results

Blocking Features¶

If a feature is blocked by external dependencies:

klondike feature block F003 --reason "Waiting for API credentials from vendor"

Resume work later:

klondike feature start F003

Import/Export¶

Export Features¶

Export features for backup or sharing:

# Export all features to YAML
klondike export-features features.yaml

# Export only not-started features
klondike export-features backlog.yaml --status not-started

# Export with all internal fields
klondike export-features full-export.yaml --all

Import Features¶

Import features from a file:

# Preview import
klondike import-features features.yaml --dry-run

# Import features
klondike import-features features.yaml

Import Format¶

Features can be imported from YAML or JSON:

# features.yaml
- description: User login with email/password
  category: core
  priority: 1
  acceptance_criteria:
    - Login form displays correctly
    - Invalid credentials show error
    - Valid credentials return JWT

- description: Password reset flow
  category: core
  priority: 2
  acceptance_criteria:
    - Reset email sent within 1 minute
    - Reset link expires after 24 hours

Best Practices¶

Feature Granularity¶

Too Big (split these up):

"Implement user authentication"
"Build the frontend"

Just Right (completable in one session):

"User can log in with email/password"
"Display loading spinner during API calls"

Too Small (combine with related work):

"Add a button"
"Change color to blue"

Acceptance Criteria¶

Good criteria are:

✅ Specific: "User sees 'Saved!' toast after clicking Save"
✅ Testable: "API returns 200 with JSON containing 'id' field"
✅ Observable: "Log file contains entry with timestamp"

Bad criteria are:

❌ Vague: "Works correctly"
❌ Unmeasurable: "Fast enough"
❌ Subjective: "Looks good"