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

Acceptance Criteria First — Define what "done" looks like before writing code. Testable criteria prevent scope creep and enable verification.
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.
Test What You Build — Use browser tools to verify each step. Don't wait until the end to discover issues.
KISS (Keep It Simple, Stupid) — Implement the simplest solution that meets the criteria. Avoid over-engineering.
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

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

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

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?
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
Define Acceptance Criteria — Write testable criteria

Acceptance Criteria Format

markdown

### 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

Check Style Guide First — Look for existing components that can be reused or extended
```
Navigate to /style-guide and snapshot to see existing components
```
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
Show All States — Document every component state:
- Default/resting
- Hover/focus
- Loading/pending
- Success/complete
- Error/invalid
- Disabled
- Empty (if applicable)
Mobile Considerations — Test responsive behavior
- Use PhoneFrame component for mobile mockups if available
- Consider touch targets (min 44px)

Style Guide Section Template

tsx

<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:

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

3.2 Frontend Integration

Wire components to backend:

State management — Zustand store or React state
API hooks — Data fetching with proper loading/error states
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

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`

Implement Events — Add PostHog capture calls

typescript

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

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

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

Run Production Build
bash
```
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.)
Check Linter
bash
```
npm run lint
```
- Fix any lint errors (warnings acceptable)
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

Update TASKS.md
- Move completed items to Completed section
- Add completion date
- Check off sub-tasks
- Add any new backlog items discovered
Update CHANGELOG.md
- Add entry under current version or "Unreleased"
- Summarize what was added/changed/fixed
- Reference any breaking changes
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:

markdown

### 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

markdown

## 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 in browser
4. Analytics	Feature working	Events instrumented
5. Build Verification	Analytics done	`npm run build` succeeds
6. Commit	Build passes	Docs updated, committed

Common Commands

bash

# 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

feature-build

NPX Install

Tags

SKILL.md Content

Feature Build Skill

Contract

Philosophy

Core Principles

Conversation Loop Model

Relationship to Other Skills

Phase 1: Task Selection

Entry Criteria

Actions

Acceptance Criteria Format

Exit Criteria

Phase 2: Component Design

Entry Criteria

Actions

Style Guide Section Template

Exit Criteria

Phase 3: Build Loop

Entry Criteria

Actions

3.1 Backend First

3.2 Frontend Integration

3.3 Browser Testing

Testing Checklist by Component Type

Loop Back Triggers

Exit Criteria

Phase 4: Analytics Setup

Entry Criteria

Actions

Event Naming Convention

Exit Criteria

Phase 5: Build Verification

Entry Criteria

Actions

Loop Back Triggers

Exit Criteria

Phase 6: Commit & Document

Entry Criteria

Actions

Conventional Commit Format

Commit Summary Block

TASKS.md Update Pattern

Exit Criteria

Quick Reference

Phase Entry/Exit Summary

Common Commands

Browser Testing Quick Reference