pos-ai: Skill for Claude Code

Feature Spec Skill

Setup

Before starting: check .handoff/sessions/ for active sessions, read context status.yaml, run git status. Follow .rules/universal.md (Plan -> Approve -> Execute).

You create persistent feature specification documents. Specs are the source of truth that survive across sessions — they prevent context loss, scope creep, and misaligned implementations.

Process

Step 1: Interview

Before writing the spec, clarify with the user:

1. What problem does this solve? — Not what to build, but why
2. Who is the user? — Which user type/persona benefits
3. What does success look like? — How do we know it's working
4. What's out of scope? — Explicit boundaries prevent creep
5. Any constraints? — Timeline, technology, compatibility requirements

If the user provides a complete description, extract these answers from their description rather than asking.

Step 2: Research Existing Context

1. Check for existing specs — ls {project_path}/docs/specs/
2. Check related features — Are there specs this feature depends on or affects?
3. Check the codebase — What already exists that this feature touches?
4. Check the data model — What entities are involved?

Step 3: Write the Spec

Use the template below. Every section is mandatory — if a section doesn't apply, explicitly state "N/A" with a reason.

Step 4: Identify Ripple Effects

Check if this spec affects other existing specs:

• Does it change a shared data model?
• Does it affect an API contract?
• Does it change user flows documented elsewhere?

If yes, note which specs need updating.

Spec Template

Save to: {project_path}/docs/specs/{feature-name}.md

# Feature Spec: {Feature Name}

**Status:** Draft | Approved | In Progress | Complete | Deprecated
**Author:** {who}
**Date:** {DATE}
**Last Updated:** {DATE}
**Project:** {project name}

---

## Problem Statement

{What problem exists? Why does it matter? What's the cost of not solving it?}

## User Story

As a {user type}, I want to {action}, so that {benefit}.

## Requirements

### Must Have
1. {Requirement — specific, testable}
2. {Requirement}

### Should Have
1. {Requirement}

### Won't Have (Explicit Scope Exclusions)
1. {What this feature explicitly does NOT include, and why}

## Design

### User Flow
1. User {action}
2. System {response}
3. User sees {outcome}

### Data Model Changes
{New tables, columns, or relationships needed}

| Table | Column | Type | Notes |
|-------|--------|------|-------|
| {table} | {column} | {type} | {constraints, defaults} |

### API Changes
{New or modified endpoints}

| Method | Endpoint | Request | Response | Auth |
|--------|----------|---------|----------|------|
| POST | /api/v1/{resource} | `{ field: type }` | `{ data: ... }` | Required |

### UI Changes
{Screens or components affected — describe layout and behavior}

## Edge Cases

1. **{Edge case}** — {How it should be handled}
2. **{Edge case}** — {How it should be handled}

## Dependencies

- **Internal:** {Other features or services this depends on}
- **External:** {Third-party APIs, libraries, or services}

## Acceptance Criteria

- [ ] {Testable criterion 1}
- [ ] {Testable criterion 2}
- [ ] {Testable criterion 3}

## Open Questions

- [ ] {Question that needs answering before implementation}

---

## Changelog

| Date | Author | Change |
|------|--------|--------|
| {DATE} | {who} | Initial draft |