documenting-features

Documenting Features

Create comprehensive feature requirement documents that capture user stories, functional requirements, edge cases, and acceptance criteria.

When to Use This Skill

• User requests feature requirements or specifications
• Defining a new CLI command or API endpoint
• Documenting expected behavior for implementation
• Creating acceptance criteria for a feature

Flexibility

Adapt sections based on feature type:

• CLI commands: Include full Command Syntax section with arguments, options, examples
• API endpoints: Include API Integration section, skip Command Syntax
• UI features: Focus on user flows and interactions, skip command syntax
• Internal features: May skip user-facing documentation sections

Arguments

• When argument is provided: Use the argument as a pre-filled feature name or title. If the argument uses #<number> syntax (e.g., #14) or Jira format (e.g., PROJ-123), delegate to the orchestrator or managing-work-items fetch #N (or managing-work-items fetch PROJ-123) to retrieve issue data, then use the returned title and body to pre-fill the requirements template. If the fetch fails (non-existent issue, network error, auth failure), warn the user and continue with manual input.
• When no argument is provided: Prompt the user interactively for the feature scope, purpose, and details.

Note: Direct gh CLI usage for issue fetch has been replaced by the centralized managing-work-items skill, which handles both GitHub Issues (#N) and Jira (PROJ-123) backends with automatic detection and graceful degradation. This skill does not have Bash in its allowed-tools, so issue fetching must be delegated.

Quick Start

1. Identify the feature scope and purpose
2. Ask for GitHub issue URL if not provided (optional but recommended for traceability)
3. Define the user story and priority
4. Document command syntax/API interface (if applicable)
5. List functional and non-functional requirements
6. Specify output format, edge cases, and testing requirements

File Locations

• requirements/features/ - Feature requirement documents
• requirements/implementation/ - Implementation plans
• docs/features/ - User-facing feature documentation

Template

See assets/feature-requirements.md for the full template.

Structure Overview

# Feature Requirements: [Feature Name]
- Overview, Feature ID, GitHub Issue (optional), Priority
- User Story
- Command Syntax (for CLI) or API Integration (for APIs)
- Functional Requirements (FR-1, FR-2, ...)
- Output Format
- Non-Functional Requirements (NFR-1, NFR-2, ...)
- Dependencies
- Edge Cases
- Testing Requirements
- Acceptance Criteria

Numbering Conventions

• FR-1, FR-2: Functional requirements - specific behaviors
• NFR-1, NFR-2: Non-functional requirements - performance, security, error handling

Verification Checklist

Before finalizing, verify:

• User story captures "who, what, why"
• All arguments/options documented with defaults
• Output format specified with example
• Error handling covers failure modes
• Edge cases identified
• Acceptance criteria are testable

Reference Examples

• feature-requirements-example-search-command.md - CLI search command with API integration
• feature-requirements-example-episodes-command.md - CLI command with date filtering and formatting

Relationship to Other Skills

Task Type	Recommended Approach
New feature with requirements	Use this skill (documenting-features)
Chore/maintenance task	Use documenting-chores skill
Bug or defect report	Use documenting-bugs skill

After documenting a feature, run /reviewing-requirements to verify the document against the codebase and docs. Then use /creating-implementation-plans to plan the implementation, followed by /documenting-qa to create a test plan. Optionally run /reviewing-requirements again for test-plan reconciliation. After /implementing-plan-phases and PR review, optionally run /reviewing-requirements for code-review reconciliation, then /executing-qa to verify, and /finalizing-workflow to merge.