name: feature-ticket-processor description: Process feature tickets from markdown files exported from any ticket system (Linear, GitHub Issues, Jira, Asana, ClickUp, etc.). Extracts requirements, converts design images to ASCII, generates JSON state files, and manages development progress using the Ralph Wiggum methodology. Use when (1) processing feature request tickets, (2) tracking feature development progress, (3) running acceptance criteria verification, (4) working with ticket markdown files, or (5) implementing systematic one-feature-at-a-time workflows.

Feature Ticket Processor

Process feature tickets from markdown exports, track development progress, and automate QA verification using the Ralph Wiggum methodology.

Workflow Decision Tree

1. Processing a new ticket? → Run process_ticket.py to parse and create state file

2. Tracking implementation progress? → Use state_manager.py to update status and record changes

3. Running QA verification? → Run qa_runner.py to execute tests and update AC status

4. Following Ralph Wiggum workflow? → Use ralph_wiggum_engine.py for systematic progression

Quick Start

Process a Ticket

# Auto-detect format and process
uv run scripts/process_ticket.py ticket.md

# Specify ticket system format
uv run scripts/process_ticket.py ticket.md --format linear

# Use custom field mappings
uv run scripts/process_ticket.py ticket.md --config config/my_system.yaml

# Start in understanding phase
uv run scripts/process_ticket.py ticket.md --status understanding

Output: Creates {TICKET_ID}_state.json with structured data.

Track Progress

# Update status
uv run scripts/state_manager.py update TICKET_state.json --status in_progress

# Record changed file
uv run scripts/state_manager.py update TICKET_state.json --add-file src/auth/login.py

# Add blocker
uv run scripts/state_manager.py update TICKET_state.json --add-blocker "Waiting on API spec"

# Query state
uv run scripts/state_manager.py query TICKET_state.json --summary

Run QA Verification

# Run all tests
uv run scripts/qa_runner.py TICKET_state.json --test-path tests/

# Rerun failed tests only
uv run scripts/qa_runner.py TICKET_state.json --rerun-failed

# Generate QA report
uv run scripts/qa_runner.py TICKET_state.json --report qa_report.md

Ralph Wiggum Workflow

# Check workflow status
uv run scripts/ralph_wiggum_engine.py status ./tickets

# Find next feature
uv run scripts/ralph_wiggum_engine.py next ./tickets

# Advance to next phase
uv run scripts/ralph_wiggum_engine.py advance TICKET_state.json

# Get phase guidance
uv run scripts/ralph_wiggum_engine.py guide TICKET_state.json

Core Workflows

1. Initial Ticket Processing

1. Receive markdown ticket file
2. Detect or specify ticket system format
3. Parse markdown to extract:
   - Metadata (ID, title, priority, assignee)
   - Acceptance criteria (enumerated list)
   - Design image references
4. Process design images → ASCII + text description
5. Generate initial JSON state file
6. Initialize Ralph Wiggum state (phase: not_started)

2. Ralph Wiggum Methodology

Phase progression:

not_started → understanding → implementing → testing → completed

Rules:

• One feature at a time
• Cannot skip phases
• Cannot advance from testing without 100% pass rate
• Features processed by priority (critical → high → medium → low)

See references/RALPH_WIGGUM.md for detailed methodology guide.

3. QA Verification

1. Map each AC to test reference (pytest nodeid)
2. Execute test suite
3. Parse results and update AC test_status
4. Calculate pass rate
5. If 100%: can advance to completed
6. If <100%: remain in testing, fix failures

See references/TESTING_GUIDE.md for test setup details.

Supported Ticket Systems

Auto-detected via content markers:

| System | Markers | Config File | |--------|---------|-------------| | Linear | LIN-, linear.app | config/linear.yaml | | GitHub | GH-, #123 | config/github.yaml | | Jira | PROJ-123 | built-in | | Asana | asana.com | config/asana.yaml | | ClickUp | CU- | built-in | | Azure DevOps | AB# | built-in |

For custom systems, copy config/custom.yaml.template and configure field mappings.

See references/FIELD_MAPPING.md for configuration details.

State File Schema

Key fields in {ticket_id}_state.json:

{
  "ticket_id": "PROJ-123",
  "status": "in_progress",
  "acceptance_criteria": [
    {
      "id": "AC-1",
      "description": "...",
      "status": "completed",
      "test_status": "passed",
      "test_reference": "tests/test_foo.py::test_bar"
    }
  ],
  "qa_summary": {
    "total_acs": 5,
    "passed": 4,
    "failed": 1,
    "pass_rate": 80.0
  },
  "ralph_wiggum_state": {
    "current_phase": "testing",
    "phases_completed": ["understanding", "implementing"]
  }
}

Full schema: references/JSON_SCHEMA.md

Scripts Reference

| Script | Purpose | |--------|---------| | process_ticket.py | Main entry point - parse ticket and create state | | parse_markdown.py | Extract structured data from markdown | | image_to_ascii.py | Convert design images to ASCII art | | state_manager.py | Create/update/query JSON state files | | qa_runner.py | Execute tests and update AC status | | config_loader.py | Manage field mapping configurations | | ralph_wiggum_engine.py | Orchestrate workflow progression |

Dependencies

Required Python packages:

pyyaml>=6.0
pillow>=10.0
pytest>=7.4

Optional:

pytesseract>=0.3  # OCR for image text extraction

Install: uv add pyyaml pillow pytest

For OCR: Install tesseract-ocr system package.

References

• references/TICKET_STRUCTURE.md - Expected markdown format
• references/JSON_SCHEMA.md - State file schema
• references/RALPH_WIGGUM.md - Methodology guide
• references/TESTING_GUIDE.md - QA testing setup
• references/FIELD_MAPPING.md - Configuration guide

Examples

Sample tickets: assets/examples/sample_ticket_*.md Sample state: assets/examples/sample_state.json