faysilalshareef/feature-tracking

Feature Tracking — Directory Structure & Status

Core Principles

• Every feature gets a numbered directory under .dotnet-ai-kit/features/
• Status progresses: planned -> specified -> implementing -> implemented -> reviewing -> shipped
• Feature brief captures scope, acceptance criteria, and affected services
• Spec captures technical design before implementation begins
• Implementation log tracks what was done for handoff purposes

Key Patterns

Feature Brief Template

# Feature: {Feature Name}

## Overview
{One-paragraph description of the feature}

## Acceptance Criteria
- [ ] {Criterion 1}
- [ ] {Criterion 2}
- [ ] {Criterion 3}

## Affected Services
- [ ] {domain}-command: {what changes}
- [ ] {domain}-query: {what changes}
- [ ] {domain}-gateway: {what changes}

## Dependencies
- Requires feature #{NNN} to be implemented first
- External: {any external dependencies}

## Estimated Scope
- Events: {count} new event types
- Endpoints: {count} new API endpoints
- UI: {count} new pages/dialogs

Technical Spec Template

# Spec: {Feature Name}

## Events
| Event Type | Data Fields | Produced By | Consumed By |
|---|---|---|---|
| OrderExportRequested | ExportFormat, Filters | command | processor |

## Aggregate Changes
- `Order` aggregate: add `RequestExport(format)` method
- New event: `OrderExportRequestedData(ExportFormat, DateTime)`

## Query Changes
- New query: `GetExportStatusQuery(Guid exportId)`
- New entity: `ExportJob` with status tracking

## API Endpoints
| Method | Path | Description |
|---|---|---|
| POST | /api/v1/orders/export | Request export |
| GET | /api/v1/orders/export/{id}/status | Check status |

## UI Changes
- Add "Export" button to Orders data grid toolbar
- Add export status dialog

Status Transitions

planned → specified    (spec written)
specified → implementing (implementation started)
implementing → implemented (code complete)
implemented → reviewing (PR created)
reviewing → approved (review passed)
approved → shipped (deployed)

Blocked transitions:
reviewing → implementing (fix required, back to implementation)

Querying Feature Status

# List all features and their status
for f in .dotnet-ai-kit/features/*/status.json; do
  echo "$(dirname $f | xargs basename): $(cat $f | jq -r .phase)"
done

# Find features in a specific phase
grep -rl '"phase": "implementing"' .dotnet-ai-kit/features/*/status.json

Anti-Patterns

| Anti-Pattern | Correct Approach | |---|---| | No feature directory | Create directory before starting work | | Skipping spec phase | Always write spec before implementing | | Stale status files | Update status.json at each phase transition | | Feature too large | Break into sub-features with dependencies |

Detect Existing Patterns

# Find feature tracking directory
ls -la .dotnet-ai-kit/features/ 2>/dev/null

# Count features by status
grep -c '"phase"' .dotnet-ai-kit/features/*/status.json 2>/dev/null

Adding to Existing Project

1. Check existing feature numbering — continue the sequence
2. Use existing templates for brief and spec
3. Update status.json when phases change
4. Link PRs to feature directories in commit messages
5. For multi-repo features, create feature directory in the primary repo