skill-system-review

What this skill does

# skill-system-review

Bridge between OMO Prometheus and the TKT ticket lifecycle.

**Two directions**:
1. **Review** — After bundle closes, assemble structured review context for Prometheus to evaluate
2. **Plan→TKT** — Convert Prometheus plans into TKT roadmap bundles and worker tickets

## Operations

### generate-review-prompt

Generate a structured review context from a completed/active ticket for Prometheus review.

```bash
python3 "<this-skill-dir>/scripts/review_prompt.py" generate-review-prompt --ticket-id <TKT-XXX>
```

**Input**: `--ticket-id` (required) — the ticket to build review context for
**Output**: JSON with `review_context`, `prometheus_prompt`, `expected_output_format`

Reads:
- Bundle `review.yaml` (stub generated by `tkt.sh close`)
- All completed ticket results in the bundle
- Audit ticket (TKT-A00) findings
- Current `roadmap.yaml` state

### generate-startup-review-prompt

Generate a review overview prompt for Prometheus at session startup (no active ticket context).

```bash
python3 "<this-skill-dir>/scripts/review_prompt.py" generate-startup-review-prompt
```

**Output**: JSON with `roadmap_summary`, `bundles`, `prometheus_prompt`

### generate-startup-review

Generate a compact startup context summary for the next session.

```bash
python3 "<this-skill-dir>/scripts/review_prompt.py" generate-startup-review
```

**Output**: JSON with `context_summary`, `roadmap_summary`, `bundles`

- includes `carryover_bundles[]` when reviewed bundles still have carryover work

### suggest-roadmap-update

Suggest roadmap changes from findings/issues without mutating `roadmap.yaml`.

```bash
python3 "<this-skill-dir>/scripts/review_prompt.py" suggest-roadmap-update --input findings.json
```

**Output**: JSON `suggestions[]` with `{phase, section, change_type, description, rationale}`

### plan-to-bundle

Convert a Prometheus plan file (`.sisyphus/drafts/*.md`) into TKT bundle creation commands.

```bash
python3 "<this-skill-dir>/scripts/review_prompt.py" plan-to-bundle --plan-file <path>
```

**Input**: `--plan-file` (required) — path to Prometheus plan markdown
**Output**: JSON with `route`, `goal`, `tickets[]`, `tkt_commands[]` (ready-to-execute shell commands)

Parsing rules:
- `## ` or `### ` headings with TODO/task keywords → ticket titles
- `- [ ]` checkboxes → individual worker tickets
- Dependency markers (`depends on`, `after`, `blocks`) → `depends_on` fields
- Effort estimates → ticket description metadata
- Categories (`visual-engineering`, `deep`, `quick`, etc.) → ticket `category`
- `### WAVE N` headings → ticket `wave` metadata for following tasks
- Structured ticket metadata lines (category, effort, acceptance, source metadata, skills, QA scenarios) → preserved into ticket objects and generated TKT commands
- Tiny plans can route to express without filename mentions when they stay within the no-dependency, no-effort fast path

### write-review-inbox

Write Prometheus review feedback into the Review Agent Inbox format for `refresh_review_inbox()` ingestion.

```bash
python3 "<this-skill-dir>/scripts/review_prompt.py" write-review-inbox --input <json-file>
```

**Input**: JSON file with `discussion_points[]`, `next_actions[]`, `batch_id`
**Output**: Appends `## Review Agent Inbox` + `# TICKET_BATCH` section to `note/note_tasks.md`

### generate-dispatch

Generate a worker dispatch view from bundle ticket state.

```bash
python3 "<this-skill-dir>/scripts/review_prompt.py" generate-dispatch --bundle B-001 [--tickets TKT-001,TKT-002]
python3 "<this-skill-dir>/scripts/review_prompt.py" generate-dispatch --auto
```

**Input**: `--bundle` (required), optional `--tickets` comma list
**Output**: human-readable wave summary plus last-line JSON containing grouped dispatch waves

Rules:
- without `--tickets`, emit currently open worker tickets only
- preserve bundle dependency order into `dispatch_wave`
- include one-line summary and effort estimate for each ticket
- `--auto` creates the suggested next bundle from `suggest-next-bundle` and immediately emits dispatch for it

### suggest-next-bundle

Suggest the next bundle goal and seed tickets from roadmap/open work/carryover.

```bash
python3 "<this-skill-dir>/scripts/review_prompt.py" suggest-next-bundle
```

**Output**: JSON with `goal`, `suggested_tickets[]`, `open_issues[]`

## Integration with OMO Prometheus

### Prometheus as Review Agent

When a TKT bundle closes:
1. `tkt.sh close` generates `review.yaml` stub
2. PM Agent calls `generate-review-prompt` to assemble review context
3. Prometheus receives the structured context and produces:
   - `summary` — what was accomplished
   - `discussion_points[]` — trade-offs, concerns, questions for user
   - `next_actions[]` — follow-up work items
   - `quality_assessment` — structured quality evaluation
4. `write-review-inbox` converts Prometheus output into TKT-ingestible tickets
5. `refresh_review_inbox()` picks up new tickets automatically

### Prometheus as Roadmap Planner

When a user makes a new request through Prometheus:
1. Prometheus conducts structured interview (OMO default behavior)
2. Prometheus writes plan to `.sisyphus/drafts/`
3. `plan-to-bundle` reads the plan and generates TKT commands
4. PM Agent executes the commands to create roadmap goal + bundle + worker tickets
5. OMO dispatches agents to claim and execute tickets

### Prompt Reference

- `prompts/prometheus-tkt-integration.md` — Instructions for Prometheus on how to use TKT roadmap/bundle system
- `prompts/question-protocol.md` — Structured questioning guide for all scenarios (requirements, branch decisions, review discussion, roadmap planning). Implements the `question_tool_first` policy from `config/tkt.yaml`.

## Compatibility

- **tickets.py alignment**: `review_prompt.py` path matches the hardcoded reference at `tickets.py:2468-2470`
- **Review Inbox format**: Output matches `parse_review_agent_inbox()` expected format (`## Review Agent Inbox` + `# TICKET_BATCH`)
- **Scope rules**: Referenced in 14+ ticket scope `allowed_prefixes` entries in `tickets.py`

```skill-manifest
{
  "schema_version": "2.0",
  "id": "skill-system-review",
  "version": "1.0.0",
  "capabilities": [
    "review-generate",
    "review-startup",
    "review-startup-summary",
    "review-roadmap-suggestion",
    "review-plan-to-bundle",
    "review-generate-dispatch",
    "review-suggest-next-bundle",
    "review-write-inbox"
  ],
  "effects": ["fs.read", "fs.write"],
  "operations": {
    "generate-review-prompt": {
      "description": "Assemble structured review context from completed ticket/bundle for Prometheus",
      "input": { "ticket_id": { "type": "string", "required": true } },
      "output": { "description": "Review context JSON", "fields": { "review_context": "object", "prometheus_prompt": "string" } },
      "entrypoints": {
        "unix": ["python3", "{skill_dir}/scripts/review_prompt.py", "generate-review-prompt", "--ticket-id", "{ticket_id}"]
      }
    },
    "generate-startup-review-prompt": {
      "description": "Generate Prometheus review overview at session startup",
      "input": {},
      "output": { "description": "Startup review context JSON", "fields": { "roadmap_summary": "object", "bundles": "array", "prometheus_prompt": "string" } },
      "entrypoints": {
        "unix": ["python3", "{skill_dir}/scripts/review_prompt.py", "generate-startup-review-prompt"]
      }
    },
    "generate-startup-review": {
      "description": "Generate compact startup context summary from roadmap and recent bundle reviews",
      "input": {},
      "output": { "description": "Startup summary JSON", "fields": { "context_summary": "string", "roadmap_summary": "object", "bundles": "array" } },
      "entrypoints": {
        "unix": ["python3", "{skill_dir}/scripts/review_prompt.py", "generate-startup-review"]
      }
    },
    "suggest-roadmap-update": {
      "description": "Suggest roadmap updates from findings/issues without mutating roadmap.yaml",
      "input": {