Feature Build Skill

Orchestrates the complete feature development lifecycle with clear phases, entry/exit criteria, and conversation loop patterns. This skill transforms feature requests into shipped, tested, and documented code.

Contract

Inputs:

• Feature request or task from TASKS.md
• Project with existing component structure (components/ui/)
• (Optional) Style guide page for component development

Outputs:

• Working feature verified in browser
• Components exported from barrel file
• PostHog analytics instrumented
• TASKS.md and CHANGELOG.md updated
• Clean git commit(s) with conventional format

Success Criteria:

• All acceptance criteria pass in browser testing
• No console errors or build failures
• Analytics events firing correctly
• Documentation updated

Philosophy

Core Principles

1. Acceptance Criteria First — Define what "done" looks like before writing code. Testable criteria prevent scope creep and enable verification.

2. Components Live in Style Guide — Every UI component starts in the style-guide page. This ensures reusability, documents all states, and provides a living reference.

3. Test What You Build — Use browser tools to verify each step. Don't wait until the end to discover issues.

4. KISS (Keep It Simple, Stupid) — Implement the simplest solution that meets the criteria. Avoid over-engineering.

5. Loop Back, Don't Push Forward — When something doesn't work, return to the appropriate phase rather than patching around issues.

Conversation Loop Model

Features are built through phases that can loop back when issues arise:

┌───────────────────────────────────────────────────────────────────────────────┐
│                                                                               │
│  ┌──────────┐   ┌──────────┐   ┌──────────┐   ┌──────────┐   ┌─────────────┐ │
│  │  Task    │──▶│Component │──▶│  Build   │──▶│Analytics │──▶│   Build     │ │
│  │Selection │   │ Design   │   │  Loop    │   │  Setup   │   │Verification │ │
│  └──────────┘   └──────────┘   └──────────┘   └──────────┘   └─────────────┘ │
│       ▲              │              │              │               │          │
│       │              ▼              ▼              ▼               ▼          │
│       │         ◀────────────◀─────────────◀──────────────────────────────────│
│       │         (loop back if criteria fail or build errors)                  │
│       │                                                                       │
│       │                                                    ┌──────────────┐   │
│       └────────────────────────────────────────────────────│   Commit &   │◀──│
│                (next feature)                              │  Document    │   │
│                                                            └──────────────┘   │
└───────────────────────────────────────────────────────────────────────────────┘

Relationship to Other Skills

• design-system — Reference for UI patterns, component design principles, style-guide template
• feature-gating — Use when building pro/freemium features with PostHog flags
• versioning — Follow semantic versioning for releases

Phase 1: Task Selection

Entry Criteria

• Fresh conversation or user requests a feature
• TASKS.md exists in project

Actions

1. Read TASKS.md — Identify the next item from Current Sprint

   Read TASKS.md and identify the next unchecked item in Current Sprint
   

2. Confirm Scope — Clarify with user what's included and excluded

   • What exactly should this feature do?
   • What should it NOT do?
   • Are there edge cases to consider?

3. Break Down if Complex — Split large features into sub-tasks

   • Each sub-task should be completable in one conversation
   • Sub-tasks should have clear dependencies

4. Define Acceptance Criteria — Write testable criteria

Acceptance Criteria Format

### Feature: [Name]

**Acceptance Criteria:**
- [ ] User can [specific action]
- [ ] System [specific behavior] when [condition]
- [ ] Error case: [scenario] displays [message]
- [ ] Mobile: [behavior] works on viewport < 768px

Exit Criteria

• Feature scope is clearly defined
• Acceptance criteria are written and agreed
• Sub-tasks identified if feature is complex

Phase 2: Component Design

Entry Criteria

• Feature scope is clear
• Acceptance criteria are defined

Actions

1. Check Style Guide First — Look for existing components that can be reused or extended

   Navigate to /style-guide and snapshot to see existing components
   

2. Design in Style Guide — Build new components in the style-guide page

   • Components should be isolated and reusable
   • Import from

     components/ui/

     barrel file
   • Export new components from barrel file

3. Show All States — Document every component state:

   • Default/resting
   • Hover/focus
   • Loading/pending
   • Success/complete
   • Error/invalid
   • Disabled
   • Empty (if applicable)

4. Mobile Considerations — Test responsive behavior

   • Use PhoneFrame component for mobile mockups if available
   • Consider touch targets (min 44px)

Style Guide Section Template

<section id="my-component">
  <SectionHeader title="My Component" />
  
  <div className="space-y-6">
    <h4 className="text-xs font-medium text-muted-foreground uppercase tracking-wide">
      Variants
    </h4>
    <div className="flex flex-wrap gap-3">
      <MyComponent variant="default" />
      <MyComponent variant="secondary" />
    </div>
    
    <h4 className="text-xs font-medium text-muted-foreground uppercase tracking-wide">
      States
    </h4>
    <div className="flex flex-wrap gap-3">
      <MyComponent loading />
      <MyComponent disabled />
      <MyComponent error="Error message" />
    </div>
  </div>
</section>

Exit Criteria

• Components visible in

  /style-guide

• All states documented and interactive
• Components exported from

  components/ui/index.ts

• Responsive behavior verified

Phase 3: Build Loop

Entry Criteria

• Components designed and in style-guide
• Acceptance criteria ready for testing

Actions

3.1 Backend First

Build data layer and API before wiring to UI:

1. Database schema — Add migrations if needed
2. Service layer — Business logic functions
3. API routes — REST endpoints with Zod validation
4. Test API — Use browser network panel or curl to verify

3.2 Frontend Integration

Wire components to backend:

1. State management — Zustand store or React state
2. API hooks — Data fetching with proper loading/error states
3. Component wiring — Connect UI to state and actions

3.3 Browser Testing

Test at each step using Cursor browser tools:

1. Navigate to the page being tested
2. Snapshot to get element references
3. Interact with elements (click, type, etc.)
4. Re-snapshot after state changes
5. Verify expected behavior
6. Screenshot if visual verification needed

See

references/testing-patterns.md

Testing Checklist by Component Type

Forms:

• Valid submission works
• Validation errors display correctly
• Loading state during submission
• Success feedback shown
• Error handling for API failures

Lists/Tables:

• Items render correctly
• Empty state displays
• Pagination/infinite scroll works
• CRUD operations update UI
• Loading skeleton shows

Modals/Dialogs:

• Opens on trigger
• Closes on backdrop click
• Closes on escape key
• Form inside modal works
• Focus management correct

Navigation:

• Routes load correctly
• Active state shows current page
• Mobile menu works
• Deep links work

Loop Back Triggers

Return to Phase 2 if:

• Component needs additional states not designed
• UI pattern isn't working as expected
• Need to refactor component API

Return to Phase 1 if:

• Scope is unclear or expanding
• Acceptance criteria need revision
• Feature should be split differently

Exit Criteria

• All acceptance criteria pass in browser
• No console errors
• Mobile viewport tested (if applicable)
• Error states handled gracefully

Phase 4: Analytics Setup

Entry Criteria

• Feature is working in browser
• All acceptance criteria pass

Actions

1. Identify Tracking Needs — What user actions matter?

   Feature Type	Typical Events
   Form	{form}_submitted , {form}_error
   Feature	{feature}_used , {feature}_completed
   Navigation	{page}_viewed
   Pro Feature	{feature}_attempted , {feature}_upgrade_shown

2. Implement Events — Add PostHog capture calls

   posthog.capture('{feature}_{action}', {
     feature: 'feature-name',
     // action-specific properties
   })
   

3. Create Dashboard (if appropriate) — Use PostHog MCP tools

   Use mcp_posthog-study-bible_dashboard-create for new dashboards
   Use mcp_posthog-study-bible_insight-create-from-query for insights
   

4. Pro Features — If feature is gated, follow feature-gating skill:

   • Create PostHog feature flag
   • Implement

     useProFeature()

     hook
   • Track

     _attempted

     ,

     _upgrade_shown

     ,

     _upgrade_clicked

     events

Event Naming Convention

{feature}_{action}

Examples:
- notes_created
- notes_synced
- chat_message_sent
- upgrade_modal_shown
- model_changed

Exit Criteria

• Key user actions instrumented
• Events firing correctly (verify in PostHog)
• Dashboard created (if feature warrants it)
• Pro feature flags configured (if applicable)

Phase 5: Build Verification

Entry Criteria

• Feature is working in browser
• Analytics implemented (or skipped if not applicable)

Actions

1. Run Production Build

   npm run build
   

   • Must complete with exit code 0
   • Fix any TypeScript errors
   • Fix any framework-specific build errors (unused exports, client/server boundaries, etc.)

2. Check Linter

   npm run lint
   

   • Fix any lint errors (warnings acceptable)

3. Verify No Regressions

   • If build fails, loop back to Phase 3 to fix issues
   • Do NOT proceed to commit until build passes

Loop Back Triggers

Return to Phase 3 if:

• TypeScript errors in new/modified files
• Build errors related to imports or exports
• Client/server component boundary issues

Exit Criteria

• npm run build

  succeeds with exit code 0

• npm run lint

  passes (no errors)
• No TypeScript errors

Phase 6: Commit & Document

Entry Criteria

• Feature complete and tested
• Analytics implemented
• Build verification passed

Actions

1. Update TASKS.md

   • Move completed items to Completed section
   • Add completion date
   • Check off sub-tasks
   • Add any new backlog items discovered

2. Update CHANGELOG.md

   • Add entry under current version or "Unreleased"
   • Summarize what was added/changed/fixed
   • Reference any breaking changes

3. Stage and Commit

   • Use conventional commit format
   • Keep commits atomic (one logical change per commit)

Conventional Commit Format

<type>(<scope>): <subject>

Types: feat, fix, docs, style, refactor, perf, test, chore, ci, build, revert

Commit Summary Block

Provide at end of feature for easy copy-paste:

### Done

**Summary**: [Brief description of what was built]

**Commits** (ohmyzsh):
gaa && gcmsg "feat(scope): add feature description"
gcmsg "fix(scope): fix related issue"
gp

TASKS.md Update Pattern

## Completed

- [x] Feature name (YYYY-MM-DD)
  - [x] Sub-task 1 ✓
  - [x] Sub-task 2 ✓
  - [x] Sub-task 3 ✓

Exit Criteria

• TASKS.md updated with completion status
• CHANGELOG.md updated with feature summary
• Clean commit(s) with conventional format
• Ready for next feature

Quick Reference

Phase Entry/Exit Summary

npm run build

Common Commands

# Start dev server
npm run dev

# Clear Next.js cache if issues
rm -rf .next

# Rebuild native modules
npm rebuild better-sqlite3

# Git workflow (ohmyzsh)
gaa && gcmsg "feat(scope): description"
gp

Browser Testing Quick Reference

1. mcp_cursor-ide-browser_browser_navigate → load page
2. mcp_cursor-ide-browser_browser_snapshot → get elements
3. mcp_cursor-ide-browser_browser_click/type → interact
4. mcp_cursor-ide-browser_browser_snapshot → verify changes
5. mcp_cursor-ide-browser_browser_take_screenshot → visual check