Feature Manifest Management

This skill manages the feature manifest system that tracks the relationship between features and their implementations.

DECISION POINTS

When working with code changes, use this decision tree:

Is this code change happening?
├── Creating new feature directory/component
│   ├── New feature has >5 files OR touches multiple domains
│   │   └── → CREATE new manifest (npm run feature:create)
│   └── Small utility/helper (<5 files, single purpose)
│       └── → ADD to existing related manifest
├── Modifying existing tracked files
│   ├── Files belong to known feature (check with: npm run feature:info -- --files <path>)
│   │   ├── Adding/removing files to feature
│   │   │   └── → UPDATE manifest files list + last_modified date
│   │   └── Just changing file contents
│   │       └── → UPDATE last_modified date only
│   └── Files are orphaned (not in any manifest)
│       └── → Determine owner with npm run feature:health, then UPDATE appropriate manifest
└── Removing/deprecating code
    ├── Entire feature being removed
    │   └── → SET status to 'deprecated', add deprecation changelog entry
    └── Some files being removed from feature
        └── → UPDATE manifest files list, add changelog entry

For manifest validation failures:

• Missing files → Add files to manifest or remove from filesystem
• Extra files → Remove from manifest files list
• Stale manifest (>90 days) → Update last_modified and add changelog entry
• No tests listed → Add test files or mark as technical debt

FAILURE MODES

1. Orphan File Syndrome

• Detection: npm run feature:health shows files in "Orphaned Files" section
• Cause: Files created without updating any manifest
• Fix: Run npm run feature:info -- --files <path> to find logical owner, then add files to appropriate manifest

2. Ghost Manifest References

• Detection: Validation errors about missing files that were deleted
• Cause: Files removed from codebase but not from manifest
• Fix: Edit manifest to remove deleted files from implementation.files, update last_modified, add changelog entry

3. Stale Dependency Web

• Detection: Features referencing deprecated or renamed dependencies in dependencies.internal
• Cause: Feature refactoring without updating dependent manifests
• Fix: Search codebase for references to old feature ID, update all dependent manifests

4. Test Coverage Blind Spot

• Detection: npm run feature:health shows features in "Without Tests" section
• Cause: Tests exist but not listed in manifest, or no tests written
• Fix: If tests exist, add to appropriate test section; if missing, create tests or document as technical debt

5. Manifest Explosion

• Detection: Too many tiny manifests (>20 manifests for <100 files)
• Cause: Creating manifests for every small utility
• Fix: Consolidate related small features into logical groupings, deprecate overly granular manifests

WORKED EXAMPLES

Example: Adding authentication middleware to existing API feature

1. Identify impact: New middleware affects multiple API routes

   npm run feature:info -- --files src/app/api
   # Shows: api-core.yaml owns most API files
   

2. Check current manifest:

   npm run feature:info -- api-core
   # Review current files list and dependencies
   

3. Decision: This is modifying existing feature (middleware is part of API infrastructure)

4. Update manifest: Add new middleware files to api-core.yaml:

   implementation:
     files:
       - src/app/api/middleware/auth.ts  # NEW
       - src/lib/auth-utils.ts          # NEW
       # ... existing files
   

5. Update metadata:

   dependencies:
     internal:
       - features/user-management.yaml  # NEW dependency
   history:
     last_modified: "2024-12-23"       # TODAY
   changelog:
     - version: "1.2.0"                # NEW entry
       date: "2024-12-23"
       changes:
         - "Added authentication middleware for API routes"
   

6. Validate: npm run feature:validate confirms no errors

What novice misses: Updating dependencies.internal when middleware uses user auth What expert catches: All affected API routes need the auth dependency listed

QUALITY GATES

Task is complete when ALL conditions are met:

• npm run feature:validate passes with no errors
• npm run feature:health shows no new orphaned files
• All implementation files listed in manifest exist in codebase
• All files in manifest have been modified more recently than last_modified date OR manifest updated
• If adding dependencies, all internal deps reference existing manifests
• If modifying feature, changelog has new entry with today's date
• If creating feature, manifest has at least entry_point and one implementation file
• Status field matches reality (complete features have tests, deprecated features noted)
• Any new environment variables are documented in dependencies.env_vars
• Database tables/API routes are documented if feature touches them

NOT-FOR BOUNDARIES

Do NOT use this skill for:

• Archived/legacy code → Use git-archaeology skill instead for historical analysis
• Third-party vendor files (node_modules, .next, etc.) → These are build artifacts, not features
• Configuration files (package.json, tsconfig.json, etc.) → Use project-config skill instead
• Documentation-only changes (README, docs/) → Use documentation skill instead
• Build/deployment scripts → Use devops-automation skill instead
• Test files that don't belong to features (setup files, mocks) → Use test-infrastructure skill instead

For cross-cutting concerns spanning multiple features:

• Use architecture-analysis skill to understand system boundaries first
• Then update multiple manifests consistently using this skill