refine-issue

Take one filed issue and work out what stands between it and a human's approval to hand it to an agent — then close that gap with the human rather than around them. One issue, one tracker (GitHub via gh or Linear via its MCP), picked per-repo by the same committed config the issue skill uses.

issue files an issue from a description that is fresh in someone's mind; the two work loops pick it up once it carries the ready label. This skill is the step in between — the one nothing helped with, so an issue either waited indefinitely or went to the loop under-decided. What it looks for is not "is this issue well written". It is: which decisions are still open that the loop must not make on its own? An agent handed an under-decided issue does not stall — it decides, quietly, and the choice surfaces as a fait accompli in the review.

It never applies the ready label itself. It reports that an issue has earned it; the human sets it. A skill that grants its own approval removes the only checkpoint the unattended loop has.

Opted out? If the repo config sets work to false, the AI work loop is off for the repo — there is no gate to take an issue to, so stop immediately and tell the user the work skills are turned off in .tituskirch-skills.json. An absent work block is not disabled (it falls back to defaults). Check .work == false on the resolved config before any action — and before indexing .work.*. A missing jq or config exits non-zero too, so a pass is not evidence the config was read.

Workflow

1. Load config & resolve tracker

Resolve .tituskirch-skills.json via templates/resolve-config.sh, never by reading the raw file (REFERENCE.md states how, missing jq included). The work.* section holds the tracker, the lifecycle label names and the Linear scope; issue.language (falling back to the root language) is what the answers are written in, and the root grillWith names the interview engine step 6 drives. Resolution per setting: config → default. Determine the tracker (work.tracker, falling back to issue.tracker) and confirm it is available and authenticated. Reuse the issue catalog cache for labels and teams.

The ready gate may be off. work.labels.ready resolving to false means the repo runs no approval gate at all — everything below still applies, and the report ends with the decisions that were closed instead of a label to apply. Tell "off" apart from "absent": absent means the default (ai: ready), false means the mechanic is disabled.

Config schema and all mechanics: REFERENCE.md.