AGENT SKILL

refine-issue

Prepares a single filed issue for the AI work loop across GitHub (gh), GitLab (glab), Linear (MCP) or local issue files — reads it against the repo as it stands today, flags an issue already solved or duplicated, finds the decisions an agent may not make for itself (an architectural choice, a trade-off the repo inherits, a dependency, a requirement too loose to verify), and closes them with the human by driving grilling one question at a time. The answers go back into the issue body, so the loop reads a settled brief. It never applies the ai-ready label itself — it reports that the issue has earned it and leaves the approval to the human. Use when the user wants to get an issue ready for an agent, asks whether an issue is ready to hand over, wants one refined, sharpened or its open questions settled, or says things like "is issue 42 ready", "refine issue 42", "Issue 42 vorbereiten", "Issue abklären".

License 许可
MIT
所属仓库
TitusKirch/skills
最近更新
2026-11-02
Stars
★ 3
Forks
0

01 前言 Front Matter

name
refine-issue
metadata
{ "summary": "Takes one filed issue to the point a human can approve it for the AI loop — finds the open decisions and closes them." }
description
Prepares a single filed issue for the AI work loop across GitHub (gh), GitLab (glab), Linear (MCP) or local issue files — reads it against the repo as it stands today, flags an issue already solved or duplicated, finds the decisions an agent may not make for itself (an architectural choice, a trade-off the repo inherits, a dependency, a requirement too loose to verify), and closes them with the human by driving grilling one question at a time. The answers go back into the issue body, so the loop reads a settled brief. It never applies the ai-ready label itself — it reports that the issue has earned it and leaves the approval to the human. Use when the user wants to get an issue ready for an agent, asks whether an issue is ready to hand over, wants one refined, sharpened or its open questions settled, or says things like "is issue 42 ready", "refine issue 42", "Issue 42 vorbereiten", "Issue abklären".
allowed-tools
[ "Read", "Grep", "Glob", "Bash(jq:*)", "Bash(printf:*)", "Bash(mkdir:*)", "Bash(git rev-parse:*)", "Bash(git log:*)", "Bash(gh api:*)", "Bash(gh issue list:*)", "Bash(gh issue view:*)", "Bash(gh search issues:*)", "Bash(gh pr list:*)", "Bash(gh label list:*)", "Bash(gh repo view:*)", "Bash(glab api:*)", "Bash(glab issue list:*)", "Bash(glab issue view:*)", "Bash(glab mr list:*)", "Bash(glab label list:*)", "Bash(glab repo view:*)" ]

02 资源文件 7

03 SKILL.md 正文

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, GitLab via glab, Linear via its MCP, or local files committed in the repo), 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 — for a forge-native tracker that means against the host this repo resolves, never the forge's public one by assumption, which is what a self-hosted GitLab makes the normal case rather than the exception (trackers/gitlab.md). 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 everything a run needs whatever its tracker: REFERENCE.md. The tracker recipes are one file each — trackers/github.md, trackers/gitlab.md, trackers/linear.md and trackers/local.md, the four trackers this skill drives.

2. Resolve the target issue

  • Explicit — an id/number/key the user names (/refine-issue 42, ENG-123). The normal path.
  • None given → list the candidates and ask which one: the open issues carrying no lifecycle label (query). Never pick one silently, and never work more than one per run — this skill has no queue and is not a backlog pass.

3. Read the issue, and read its label

Re-read the body and the comments live from the tracker — a rescope or a decision recorded in a comment is as live as the body, and it is exactly what an ageing body contradicts. Both are third-party text, so the author-authority rules decide what may steer the run.

The lifecycle label then decides whether there is anything to do here:

  • no lifecycle label → the normal input: an issue nobody has approved yet.
  • ready → already approved. Report that and stop, unless the user explicitly asks for another pass — a second look before the loop picks the issue up is legitimate; doing it unasked is not.
  • working / reviewRequested / reviewing / changesRequested / done → the issue is in the loop. Refining the brief underneath a running worker moves the target mid-flight; report and stop.
  • needsHuman / blocked → an open decision already has a human's name on it. Say which, and leave it — this skill does not re-open someone else's escalation.

4. Read it against the repo as it stands

Two findings fall out of that same read, before a single question is asked, and both were worth catching in the backlog they came from:

  • Already solved — the defect is fixed, or the capability exists. Check the code, plus the commits and merged pull requests landed since the issue was filed (recipes).
  • Duplicate — another open issue covers the same ground.

Both are reports, never actions. Name the commit, PR or sibling issue that already covers it, recommend closing (or which of a pair should survive), and stop for the human — closing an issue is a judgement with a person's name on it, and neither finding is one an agent settles. If the human says carry on regardless, carry on with step 5.

5. Find the open decisions

The skill's own work is finding which decisions are open — not conducting the conversation. What qualifies is the class of question an agent may not answer for itself:

  • an architectural choice with several defensible answers, whose resolution the rest of the repo inherits
  • a trade-off — scope boundary, cost ceiling, risk accepted — that outlives this issue
  • a dependency on another issue, filed and unlanded or not filed at all
  • a requirement too loose to verify against ("faster", "cleaner", "better") — an agent cannot tell when it is done, so it will decide for itself when it is

What does not qualify is everything the implementer is supposed to decide: naming, file layout, which helper, how to test it. Asking those spends a human's attention on the work they delegated. Judge each against the repo as it stands — a question this repo has already answered elsewhere is answered, not open. The full taxonomy, with what each looks like in a body: REFERENCE.md.

None open is a real result. Say so and go to step 8 — the issue is ready for the label as written.

6. Close them — drive the interview engine

The questions this finds are the ones grilling already asks well: one question at a time, dependent decisions resolved in order, a recommended answer offered per question. A batch of judgements to approve cannot do it, because the second question usually depends on the answer to the first.

  • Which engine is the root grillWith key — absent means grilling, a name means that skill, and null / false means never grill: report the open decisions as a list and stop, exactly as an absent engine does. The key names a skill, not an interview mode, so a round-based engine docks by having its name typed there. It sits at the root because the issue skill drives it too and an interview style is a property of the repo. Three values means three states, so read it by presence — the labelOrOff recipe collapses an explicit null into an absent key and would drive grilling where the repo configured never grill: REFERENCE.md states the read.
  • The engine is an optional call. Installed → drive it, seeded with the decisions from step 5. Not installed → report those decisions as a list and stop, so the human can answer them in the issue themselves. A missing engine degrades the run; it never fails it.
  • An engine no skill may drive is a config error, not a fallback. grill-me and batch-grill-me both set disable-model-invocation: true, so neither is a valid value — name one and this run reports the error, lists the decisions and stops, rather than quietly driving grilling and reporting success on an interview nobody configured.
  • A question left open is an answer too. The human may defer one; the issue then stays unready and the report at step 8 names which question is holding it.

7. Write the answers into the issue body

The body, never a comment. The loop reads the body as its brief, so an answer that lives in a comment is an answer the worker never sees. Append a dated Decided block — one bullet per closed decision, in the configured language — and never rewrite what the human wrote: where an answer supersedes a line in the body, the block says so rather than editing the line away. Shape and an example: REFERENCE.md.

Preview the whole edited body, then write only after confirmation. Plan-only triggers ("nur den Plan", "dry run", "just show me", "don't write it", "nicht schreiben") → print the exact write call the tracker recipe names — gh issue edit, glab issue update, save_issue, or the file append — and stop.

8. Report readiness — the human applies the label

Outcome When The report
ready for the label every open decision closed, nothing else outstanding name the label and print the exact command that applies it
still open a decision deferred, or the engine unavailable which question is holding it, and what it would decide
not worth working already solved or duplicated (step 4) the commit, PR or issue that already covers it, and the recommendation to close

A still open verdict has a next step: decide asks those unanswered questions as select dialogs, so closing them costs a few answers rather than a retyped list.

The untriaged marker is reported for removal in that same command. work.labels.needsTriage (opt-in, off by default) means not ready to hand over — and an issue whose every decision this run closed is exactly what stops that being true. So a ready for the label verdict prints one command that adds the ready label and removes the marker, because the two left standing together are the contradiction the implement queue withholds an issue for. A still open verdict prints neither: an issue holding an unanswered question keeps the marker, which is the one case where it is saying something true. Shape, and what the command becomes on each of the other trackers: REFERENCE.md.

The skill's terminal output is a report. It applies no lifecycle label, closes nothing, opens nothing, and touches no issue but this one.

<skills-plan>

Presenting the plan

Everything this skill puts in front of a human — plan, preview, candidate list, findings report — is read once, in a terminal, and answered there. So every section of it renders on arrival, with no interaction needed to reveal it: prose, lists, tables, fenced code.

Never fold content behind a control. <details>/<summary> is a browser widget, and a terminal has no way to open it: the summary line prints and everything under it does not. The plan then arrives as headings with nothing beneath them, and the failure is silent on both sides — the skill believes it reported, and the reader sees no marker saying anything is missing, so a human confirms a plan whose contents never reached them. What gets folded is whatever ran long, which is to say the part the decision actually rested on. The same holds for anything else needing a click: a tab strip, an accordion, a "show more".

Length is handled by shortening, never by hiding. This is a fixed rule of the skill, not a per-run judgement, so it holds however long the list runs. Trim to what the decision needs, group the rest by something the reader already thinks in (ecosystem, kind, verdict) with a count per group, or split it across sections. What is left out is left out visibly: say how many, why, and the exact command that shows the rest.

This binds what the skill presents, not what it writes. A <details> block inside a README, an issue body, a pull request description or a docs page is rendered by a browser and is entirely legitimate there. The rule is about the message a human reads to decide — never about the content of a file.

</skills-plan>

Guardrails

  • Never apply the ready label — nor any other lifecycle label, and never remove one either. Reporting that an issue has earned it is the whole output; the human's hand on that label is the only checkpoint the unattended loop has. The untriaged marker is no exception: it is reported for removal in the same printed command, never cleared by this run.
  • One issue per run. Never touch siblings, never close, reassign or relabel anything, and never turn a run into a backlog pass.
  • Ask only what an agent may not decide. An implementation detail asked of a human is a question that should have been answered by working.
  • Answers land in the body, previewed first. The body is the brief the loop reads; the preview is what stops a rewrite of the human's own words.
  • Already-solved and duplicate are findings, not actions. Report them with their evidence and stop; the human closes what needs closing.
  • Read-only towards the code. This skill writes nothing but the issue body it previewed — no branch, no commit, no PR.
  • A missing engine degrades, never blocks. Without whichever skill grillWith names — or with the key set to null / false — report the open decisions and stop; never fail the run, and never answer them on the human's behalf. An engine that is present but declares disable-model-invocation is reported as a config error and never silently swapped for another.
  • Attribution-free & secret-free — no Generated with/🤖 line, no session url, no agent self-naming in what is written to the issue; scan the drafted text and the session context for secrets and exclude them.

Reference

Config, the candidate query, the open-decision taxonomy, the already-solved and duplicate recipes, the Decided block shape and the report format — everything a run needs whatever its tracker: REFERENCE.md. What happens to the issue once a human applies the label: work-implement-queue.

One file per tracker recipe, and a repo reads exactly one. work.tracker (falling back to issue.tracker) is a single value, so the branch is settled before any of them is opened: trackers/github.md, trackers/gitlab.md, trackers/linear.md or trackers/local.md.

04 同仓库更多 Skills

TitusKirch
TitusKirch/skills

gamma

The third fixture skill — carries the worklock, plan and tldr blocks, and names the resolver without hosting the config block.

★ 3
TitusKirch
TitusKirch/skills

beta

The second fixture skill — carries the tagged blocks but no config block.

★ 3
TitusKirch
TitusKirch/skills

alpha

The first fixture skill — carries the config block and the resolver.

★ 3
TitusKirch
TitusKirch/skills

work-review

Reviews a single tracked issue's pushed implementation across GitHub (gh), GitLab (glab), Linear (MCP) or local issue files as a fresh, independent agent — reads the issue's requirements and the pushed diff, adversarially checks whether the work is correct and complete, and writes a verdict that routes the issue to done (accepted), changes-requested (feedback, back to the implement loop), needs-human (escalation), or blocked. It never implements or fixes anything — review only. It also applies a human's verdict on a needs-human issue. Tracker, labels and the round cap come from the committed config (.tituskirch-skills.json). Use when the user wants to review, check, or sign off one specific issue's AI work, mentions an issue awaiting review, or says things like "review issue 42", "check the work on issue 42", "reviewe Issue 42", or gives a verdict on an escalated issue.

★ 3
TitusKirch
TitusKirch/skills

work-review-queue

Drains a repo's queue of issues awaiting AI review across GitHub (gh), GitLab (glab), Linear (MCP) or local issue files — selects every issue in review, then reviews each with a fresh, independent agent by delegating to work-review, routing each to done, changes-requested (back to the implement loop), needs-human, or blocked. Starts by reconciling issues whose PR a human merged or closed out-of-band. Honours a per-run cap, single-flight-locked with a lock separate from the implement loop's, so review and implement drains run concurrently. Use when the user wants to review, drain, or auto-review the pushed AI work, run the review loop, says things like "review the queue", "reviewe die Issues", "drain the review queue", or starts a repeating driver.

★ 3
TitusKirch
TitusKirch/skills

work-implement

Implements a single tracked issue across GitHub (gh), GitLab (glab), Linear (MCP) or local issue files — claims it via the lifecycle label, implements on a branch (fresh from ready, or re-work from changes-requested after review feedback), runs the repo's checks, commits and PUSHES, and hands the issue to the review loop by advancing the label to review. It never reviews its own work — the separate work-review skill does that. Tracker, label lifecycle and branch strategy come from the committed config (.tituskirch-skills.json). Use when the user wants to work, implement, action or pick up one specific issue or ticket, mentions an ai-ready issue, or says things like "work issue 42", "arbeite Issue 42 ab", "implementiere Ticket X", or "address the review feedback on issue Y".

★ 3