---
name: requirements-converter
description: Convert markdown project plans into requirements.json format for ticket-manager. Use this skill when the user has a markdown project plan that needs to be converted to structured tickets, or before importing documentation into the ticket database.
---

# Requirements Converter Skill

**Version**: 1.0.0
**Category**: Conversion
**Execution Time**: Fast (<10 seconds)
**Complexity**: Low

## Purpose

Convert markdown project plans into requirements.json format compatible with ticket-manager for import into the ticket database.

## When to Use

- User provides a markdown project plan that needs to be imported as tickets
- Converting documentation or planning documents into actionable tickets
- Migrating from markdown-based planning to ticket system
- Before running ticket-manager import

## Commands

### convert

Convert markdown project plan to requirements.json

```bash
requirements-converter.sh convert <input.md> [output.json]
```

**Parameters**:
- `input.md`: Markdown file with project plan
- `output.json`: (Optional) Output file name (default: requirements.json)

**Output**: Creates requirements.json file

**Example**:
```bash
requirements-converter.sh convert PROJECT_PLAN.md
requirements-converter.sh convert plan.md my-requirements.json
```

### validate

Validate requirements.json format

```bash
requirements-converter.sh validate <requirements.json>
```

**Parameters**:
- `requirements.json`: JSON file to validate

**Output**: Validation report with epic and story counts

**Example**:
```bash
requirements-converter.sh validate requirements.json
```

## Expected Input Format

Markdown file with this structure:

```markdown
# Epic 1: Epic Title
Description of the epic

## Story 1.1: Story Title
- Acceptance criterion 1
- Acceptance criterion 2
- Acceptance criterion 3

Technical notes:
- Technical note 1
- Technical note 2

## Story 1.2: Another Story
- Acceptance criterion 1

# Epic 2: Second Epic
Description

## Story 2.1: Story in Second Epic
- Criteria 1
```

**Parsing Rules**:
- Epic headers: `# Epic <number>: <title>`
- Epic description: Non-list text between epic and first story
- Story headers: `## Story <number.number>: <title>`
- Story description: Non-list prose between the story header and the first
  bullet (or `Technical notes:` line). Multiple paragraphs separated by blank
  lines are joined with double newlines in the JSON output. A line starting
  with `- ` is always treated as a bullet, never as prose.
- Acceptance criteria: List items (`-`) before "Technical notes:" section
- Technical notes: List items after "Technical notes:" line
- Complexity: Optional `**Complexity**: <value>` marker on its own line
  anywhere within a story block. Valid values are `Low`, `Medium`, `High`,
  `Very High` (case-insensitive). Invalid values fall back to `Medium` and
  emit a warning. Missing markers default to `Medium`.
- Implementation order: Auto-assigned sequentially

## Output Format

Creates requirements.json compatible with ticket-manager:

```json
{
  "epics": [
    {
      "id": "1",
      "title": "Epic Title",
      "description": "Description of the epic",
      "user_stories": [
        {
          "id": "1.1",
          "title": "Story Title",
          "description": "",
          "acceptance_criteria": [
            "Acceptance criterion 1",
            "Acceptance criterion 2",
            "Acceptance criterion 3"
          ],
          "technical_notes": [
            "Technical note 1",
            "Technical note 2"
          ],
          "complexity": "Medium",
          "implementation_order": 1,
          "status": "TODO"
        }
      ]
    }
  ]
}
```

## Integration with Other Skills

### With ticket-manager

Convert and import in one workflow:

```bash
# Step 1: Convert markdown to JSON
requirements-converter.sh convert PROJECT_PLAN.md requirements.json

# Step 2: Import into ticket database
ticket-manager.sh import requirements.json
```

### Complete Workflow

```bash
# 1. Convert plan
requirements-converter.sh convert plan.md

# 2. Validate
requirements-converter.sh validate requirements.json

# 3. Initialize database (if needed)
ticket-manager.sh init

# 4. Import tickets
ticket-manager.sh import requirements.json

# 5. View status
ticket-manager.sh status
```

## Error Handling

**Invalid JSON output**:
- Skill validates output after conversion
- Reports validation errors before completion
- Returns non-zero exit code on failure

**Missing input file**:
- Clear error message
- Usage instructions shown

**Invalid markdown format**:
- Skips malformed sections
- Continues processing valid sections
- Warns about skipped content

## Usage Patterns

### Pattern 1: Quick Conversion

User has markdown plan, wants to import to tickets:

```bash
User: I have PROJECT_PLAN.md that I want to import as tickets

Claude:
1. Convert the markdown plan to requirements.json format
   [runs: requirements-converter.sh convert PROJECT_PLAN.md]

2. Import into ticket database
   [runs: ticket-manager.sh import requirements.json]

✓ Converted 3 epics with 12 stories
✓ Imported 12 tickets successfully
```

### Pattern 2: Validation Before Import

User wants to verify conversion before importing:

```bash
User: Convert my plan and validate before importing

Claude:
1. Convert markdown to JSON
   [runs: requirements-converter.sh convert plan.md]

2. Validate JSON format
   [runs: requirements-converter.sh validate requirements.json]

3. Review conversion results
   [shows: summary of epics and stories]

4. Import if validation passes
   [runs: ticket-manager.sh import requirements.json]
```

### Pattern 3: Custom Output File

User wants specific output filename:

```bash
User: Convert PROJECT_PLAN.md to sprint-1-requirements.json

Claude:
[runs: requirements-converter.sh convert PROJECT_PLAN.md sprint-1-requirements.json]

✓ Converted successfully to sprint-1-requirements.json
```

## Dependencies

- `jq`: JSON processing (required)
- `bash`: Version 3.2+ (standard on macOS/Linux)

## Output Messages

**Success**:
- `✓ Conversion successful`
- `✓ Output saved to: requirements.json`
- `✓ Validation successful`

**Errors**:
- `Error: jq is required but not installed`
- `Error: Input file not found: <file>`
- `✗ Invalid JSON format`
- `✗ Missing 'epics' array`

## Best Practices

1. **Validate markdown structure** before conversion
   - Check epic numbering is sequential
   - Ensure story IDs follow epic.story pattern
   - Verify list formatting is consistent

2. **Review conversion output** before importing
   - Use validate command to check JSON
   - Manually review for accuracy
   - Check epic/story counts match expectations

3. **Edit JSON if needed** after conversion
   - Adjust complexity levels
   - Modify implementation order
   - Add descriptions

4. **Keep markdown as source of truth**
   - Don't edit JSON directly for major changes
   - Update markdown and re-convert
   - Use JSON for minor tweaks only

## Tips

- Use clear, consistent heading format in markdown
- Keep epic IDs sequential (1, 2, 3...)
- Keep story IDs in epic.story format (1.1, 1.2, 2.1...)
- Use list items (`-`) consistently
- Put "Technical notes:" on its own line
- Test with small markdown files first

## Limitations

- Does not parse nested lists
- Implementation order assigned sequentially (edit JSON to change)
- Does not preserve markdown formatting in descriptions
- Epic and story IDs must follow number patterns
- Lines starting with `- ` are always treated as bullets, so prose lines
  cannot begin with a dash

## Version History

- **1.0.0** (2025-10-28): Initial requirements-converter skill