feature-build

name	feature-build
description	Complete feature development lifecycle from task selection through commit. Orchestrates component design, build loops with browser testing, PostHog analytics, and documentation updates. Use when building any new feature or enhancement.

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.

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   │ │
│  │Selection │   │ Design   │   │  Loop    │   │    Setup     │ │
│  └──────────┘   └──────────┘   └──────────┘   └──────────────┘ │
│       ▲              │              │               │          │
│       │              ▼              ▼               ▼          │
│       │         ◀────────────◀─────────────────────────────────│
│       │         (loop back if criteria fail)                   │
│       │                                                        │
│       │                                     ┌──────────────┐   │
│       └─────────────────────────────────────│   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 for detailed testing scenarios.

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: Commit & Document

Entry Criteria

• Feature complete and tested
• Analytics implemented

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

Phase	Entry	Exit
1. Task Selection	Feature request	Criteria defined
2. Component Design	Criteria clear	Components in style-guide
3. Build Loop	Components ready	All criteria pass
4. Analytics	Feature working	Events instrumented
5. Commit	Analytics done	Docs updated, committed

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