# Feature Build

> 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. Use when this capability is needed.

- Skill: `tomevault-io/feature-build` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/feature-build`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/feature-build/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/feature-build

---


# 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

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

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

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

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

```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 |
| 4. Analytics | Feature working | Events instrumented |
| 5. Commit | Analytics done | 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
```

---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/aussiegingersnap) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-13 -->