# Controller

> Orchestrates the Quay bug-fix workflow through 9 phases with confidence-based gating. Reads confidence from phase artifacts to advance automatically, post JIRA comments, or escalate to the user.

- Skill: `quay/controller` (Agent Skill)
- Install (CLI): `npx skillmds@latest add quay/controller`
- Raw SKILL.md: https://api.skillmd.com/api/skills/quay/controller/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: quay (https://skillmd.com/u/quay)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/quay/controller

---


# Quay Bugfix Controller

You manage a 9-phase bug-fix workflow with confidence-based gating. After
each phase, read the confidence assessment from the phase artifact and use
it to decide whether to advance, comment, or escalate.

## Session Bootstrap

On first run, ensure Lola plugins are installed:

```bash
bash .claude/scripts/session-setup.sh
```

## Phases

1. **Assess** — the `assess` skill
   Read the bug report, summarize understanding, identify gaps, propose a plan.

2. **Reproduce** — the `reproduce` skill
   Confirm the bug exists by reproducing it in a controlled environment.

3. **Diagnose** — the `diagnose` skill
   Trace the root cause through code analysis, git history, and hypothesis testing.

4. **Fix** — the `/dev:code` skill (from dev plugin)
   Read the root cause analysis, create a feature branch, then implement
   the minimal fix using `/dev:code`. Write implementation notes afterward.

5. **Test** — the `test` skill
   Write regression tests, run the full suite, and verify the fix holds.

6. **Review** — the `review` skill
   Critically evaluate the fix and tests — look for gaps, regressions, and missed edge cases.

7. **Document** — the `document` skill
   Create release notes, changelog entries, JIRA updates, and PR description.

8. **PR** — the `/dev:pr` skill (from dev plugin), then `/dev:poll`
   Create a pull request using `/dev:pr`, then start CI polling with
   `/dev:poll <PR#>`.

9. **Summary** — the `summary` skill
   Scan all artifacts and present a synthesized summary.

## Confidence-Based Gating

### Confidence Assessment Format

Each phase skill writes a `## Confidence Assessment` section at the bottom
of its artifact:

```markdown
## Confidence Assessment
- **Level**: high | medium | low
- **Score**: <0-100 integer>
- **Score rationale**: <1-2 sentences>
- **Open questions**: <bullet list, or "None">
```

### Confidence Flow

After each phase completes, read the confidence level from the artifact:

| Confidence | Threshold | Action |
|------------|-----------|--------|
| **High** | >=90% | Advance to next phase silently |
| **Medium** | 70-89% | Post JIRA comment with findings and open questions, then advance |
| **Low** | <70% | Post JIRA comment, then stop and escalate via `AskUserQuestion` |

### Posting JIRA Comments

When confidence is medium or low, post a structured comment:

```bash
bash .claude/scripts/jira-ops.sh comment <TICKET_KEY> "<comment_text>"
```

Format the comment as:

```text
[Phase: <phase_name>] Automated Analysis Update

Confidence: <Level> (Score: <score>/100)

Findings:
- <key finding 1>
- <key finding 2>

Open Questions:
- <question 1>
- <question 2>

Next: <what the agent will do next, or "Stopping for human input">
```

### JIRA Ticket Context

The controller needs a JIRA ticket key to post comments. The ticket key
comes from:
1. The assess phase (extracted from the bug report or user input)
2. Direct user input

If no ticket key is available, skip JIRA comments entirely and use
`AskUserQuestion` for medium-confidence escalations too.

## How to Execute a Phase

1. **Announce** the phase to the user before doing anything else.
2. **Run** the skill for the current phase.
3. **Read** the confidence assessment from the phase artifact.
4. **Act** on the confidence level per the table above.
5. If advancing, continue to the next phase.

## Recommending Next Steps

After each phase, log the natural next step. These are informational —
the agent advances automatically based on confidence, not user choice.

- After **assess**: Next is reproduce (or skip to diagnose if root cause
  is already evident from the report).
- After **reproduce**: Next is diagnose (or skip to fix if reproduction
  confirmed the cause).
- After **diagnose**: Next is fix (or re-assess if diagnosis revealed a
  different bug).
- After **fix**: Next is test. Always test before PR.
- After **test**: Next is review.
- After **review**:
  - Verdict "solid" -> document (then auto-advance through PR and summary)
  - Verdict "tests incomplete" -> test (add missing coverage)
  - Verdict "inadequate" -> fix (address review concerns, max 2 cycles)
- After **document**: Next is pr.
- After **pr**: Next is summary.

## Escalation Rules (Override Confidence)

These conditions **always** trigger escalation via `AskUserQuestion`,
regardless of the phase confidence level:

- Security vulnerability discovered
- Multiple valid solutions with unclear trade-offs
- Architectural decisions that affect other teams
- Existing PR or fix found for the same issue (assess phase)
- Review verdict "inadequate" after 2 revision cycles

## Starting the Workflow

When the user provides a bug report, issue URL, or JIRA ticket:

1. Execute the **assess** phase
2. Read the confidence assessment
3. Continue per the confidence flow

If the user invokes a specific skill directly, execute that phase — don't
force them through earlier phases.

## Rules

- **One mode.** The controller always uses confidence-based gating.
- **Recommendations come from this file, not from skills.** Skills report
  findings and confidence; this controller decides what to do next.
- **Max 2 revision cycles.** If review says "inadequate" twice, stop and
  escalate regardless of confidence.