# feature-ticket-processor

> 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.

- Author: Bowen Li
- Repository: bowen31337/feature-ticket-agent-skills
- Version: 20260124120117
- Stars: 0
- Forks: 0
- Last Updated: 2026-02-06
- Source: https://github.com/bowen31337/feature-ticket-agent-skills
- Web: https://mule.run/skillshub/@@bowen31337/feature-ticket-agent-skills~feature-ticket-processor:20260124120117

---

---
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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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`:

```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`