# Spec a Feature

You are about to create a feature specification in Gherkin format and turn it into a GitHub issue ready for implementation.

## Process

1. **Gather Requirements**
   - Ask the user for the feature name and description if not provided
   - Understand the business value and user needs
   - Identify scope, non-goals, and risks

2. **Write Gherkin Specification**
   Create a comprehensive specification including:
   - **Feature** name and description
   - **Background** (if needed)
   - **Scenarios** using Given/When/Then format
   - **Examples** with data tables where appropriate
   - **Acceptance Criteria**
   - **Non-Goals** (what this feature won't do)
   - **Risks & Mitigations**
   - **Technical Considerations**

3. **Format as GitHub Issue**
   Structure the issue with:
   - Clear title: `feat: [Feature Name]`
   - Labels: `enhancement`, `needs-implementation`
   - Milestone (if applicable)
   - Complete Gherkin specification in the body
   - Testing requirements

4. **Create the Issue**
   Use the `gh` CLI to create the issue:
   ```bash
   gh issue create --title "feat: [Feature Name]" \
     --body "[Full specification]" \
     --label enhancement \
     --label needs-implementation
   ```

## Template for Issue Body

````markdown
## Feature: [Feature Name]

### Business Value

[Describe the business value and user benefit]

### User Story

As a [type of user]
I want [goal/desire]
So that [benefit/value]

### Gherkin Specification

```gherkin
Feature: [Feature Name]
  [Feature description explaining the feature's purpose]

  Background:
    Given [common preconditions for all scenarios]

  Scenario: [Happy path scenario]
    Given [initial context]
    When [action/event]
    Then [expected outcome]
    And [additional outcomes]

  Scenario: [Edge case or error scenario]
    Given [initial context]
    When [action/event]
    Then [expected outcome]

  Scenario Outline: [Parameterized scenario if needed]
    Given [context with <parameter>]
    When [action with <parameter>]
    Then [outcome with <expected>]

    Examples:
      | parameter | expected |
      | value1    | result1  |
      | value2    | result2  |
```
````

### Acceptance Criteria

- [ ] Criterion 1
- [ ] Criterion 2
- [ ] Criterion 3

### Non-Goals

- This feature will NOT [explicitly excluded functionality]
- Out of scope: [related but excluded items]

### Risks & Mitigations

- **Risk**: [Potential risk]
  **Mitigation**: [How to address it]

### Technical Considerations

- Architecture impact: [if any]
- Performance considerations: [if any]
- Security considerations: [if any]
- Dependencies: [external dependencies or prerequisites]

### Testing Requirements

- Unit test coverage for all new functions
- Property-based tests for business logic invariants
- Integration tests for external interactions
- Edge cases and error scenarios covered

### Definition of Done

- [ ] All acceptance criteria met
- [ ] All tests passing
- [ ] Documentation updated
- [ ] Code reviewed and approved
- [ ] Changeset added
- [ ] No security vulnerabilities
- [ ] Performance requirements met

````

## Important Notes

1. **Be Specific**: Write clear, unambiguous scenarios
2. **Focus on Behavior**: Describe WHAT, not HOW
3. **Keep it Testable**: Each scenario should be verifiable
4. **Consider Edge Cases**: Include error and boundary scenarios
5. **Make it Implementable**: Provide enough detail for the `implement-github-issue` command

## Example Output

After gathering requirements, create an issue like:

```bash
gh issue create --title "feat: Add user authentication with JWT" \
  --body "## Feature: User Authentication with JWT

### Business Value
Enable secure user authentication to protect user data and provide personalized experiences.

### User Story
As a user
I want to securely log in to the application
So that I can access my personal data and features

### Gherkin Specification
[... full specification ...]" \
  --label enhancement \
  --label needs-implementation
````

The created issue will be ready for implementation using the `/implement-github-issue` command.