refine-issue
Skill17 starsChanged 3 months agoApache-2.0View on GitHub
Refine a cockpit issue into an exact implementation plan an agent can execute. Reads the target issue, investigates the real code, reproduces bugs, then overwrites the issue description with a precise build spec (files, symbols, exact changes, acceptance criteria). Use when asked to refine, plan, or work up a cockpit issue, e.g. "refine CK-12".
2 other projects use a version of this.
Adopted by
Most recently taken up by
- TitusKirch/skillstheir own version, first seen Oct 13, 2026
- pavelsimo/skillstheir own version, first seen Jul 7, 2026
Other versions2 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 2
- TitusKirch/skills★ 2same name
- pavelsimo/skills★ 1same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository7 other files it gives its agents.
- accept-issueSkill
- browser-testSkill
- implement-issueSkill
- integration-testSkill
- publish-releaseSkill
- regen-cli-commandsSkill
- review-issueSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
18 rules. About 0 are common, 13 are distinctive, and 5 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈13
Distinctive · estimate
This author's own choices. Worth a look.
5
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 27
If the description or a comment links an image, view it directly from its URL.
- Distinctive: line 29
Do not ask follow-up clarifying questions yet.
- Distinctive: line 33
Before doing any investigation, verify the issue has enough basic information to produce a useful plan.
- Very specific: line 41
Add a comment via add_issue_comment listing exactly what is missing and what the reporter should add.
- Distinctive: line 42
Stop. Do not proceed with refinement.
- Very specific: line 52
bug / regression: use the bug template from references/bug.md.
- Very specific: line 53
feature: use the feature template from references/feature.md.
- Distinctive: line 54
chore / refactor / task: use the feature template but drop UI-specific and telemetry sections.
- Very specific: line 59
Read the reference file for the classified type (relative to this SKILL.md):
- Distinctive: line 67
Use the explore guidance to direct your investigation in the next step.
- Distinctive: line 74
If the repo uses graphene, read the relevant nodes before exploring files, and record any boundary or gotcha you find.
- Distinctive: line 75
Wait for the Explore subagent to return before continuing.
- Distinctive: line 76
If it comes back with low-confidence or empty findings (e.g.
- Distinctive: line 82
If you would cite a file you have not read in this skill invocation, read it now.
- Distinctive: line 88
Check for regression: git log / git blame on the affected lines for the introducing commit.
- Distinctive: line 94
Every plan starts with:
- Distinctive: line 103
All plans must have:
- Distinctive: line 162
Wait for explicit confirmation before writing.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Refine a cockpit issue
Turn a rough cockpit issue into a precise plan another agent will execute without interpretation. The plan replaces the issue description. The bar: an implementation agent should read the plan end-to-end and start writing code without asking a single follow-up question.
Input
The issue key (e.g. CK-12) from the invocation. If none was given, ask which issue, or use mcp__cockpit-config__list_issues to show open candidates and confirm one.
Invocation modes
This skill runs in two modes. Determine which from how it was invoked.
- Pipeline (autonomous): a ticket enters
Refine Readyand an agent runs the skill end to end with no human in the loop. Perform the detail check gate, the self-review loop, all status transitions, and skip the preview/confirm step. The agent never waits for a human. - Interactive: a human runs the skill directly (e.g. "refine CK-12"). Same flow, but do the preview/confirm step before writing.
The default is pipeline mode. Treat it as interactive only when a human invoked it directly in this session.
Refinement and the adversarial review are one stage. The skill investigates once (warm context), then self-reviews and fixes in the same run, posting each review round's findings as a comment. There is no separate review stage in the autonomous pipeline. The issue moves Refining -> Plan Review directly.
Steps
1. Read the issue and resolve the repo
mcp__cockpit-config__get_issuefor the key. One call returns the full title, description verbatim, labels, status, and every comment — capture all of it, including any context a reporter left in a comment.- Resolve the repo to investigate:
list_projects, match the issue'sprojectId, and use that project'srepoPathif set. Otherwise use the session's current working directory (today's behaviour, and the only case while cockpit is the sole project). Investigation and file reads in the steps below happen in that repo. - If the description or a comment links an image, view it directly from its URL; attachments returned by
get_issueare also plain URLs, viewable directly.
Do not ask follow-up clarifying questions yet. The Explore step often answers them.
2. Detail check gate
Before doing any investigation, verify the issue has enough basic information to produce a useful plan. Required details depend on type:
- Bug: what is broken, how to trigger it, expected vs actual behaviour.
- Feature: what the user should be able to do that they cannot do today.
- Chore / task: what needs to change and why.
If details are missing:
- Set the issue status to
Needs Detailviaupdate_issue(key + status). - Add a comment via
add_issue_commentlisting exactly what is missing and what the reporter should add. - Stop. Do not proceed with refinement.
In interactive mode, surface the gaps to the human and ask whether to proceed anyway before moving to Needs Detail.
If details are sufficient:
- Set the issue status to
Refiningviaupdate_issue(key + status). - Continue to step 3.
3. Classify
Decide the type from labels first, else infer from content:
- bug / regression: use the bug template from
references/bug.md. - feature: use the feature template from
references/feature.md. - chore / refactor / task: use the feature template but drop UI-specific and telemetry sections.
State the classification before planning.
4. Load the per-type template
Read the reference file for the classified type (relative to this SKILL.md):
references/bug.mdfor bugs and regressionsreferences/feature.mdfor features, chores, and tasks
The reference file contains two things:
- Explore guidance: what to investigate and what to quote from the codebase.
- Template sections: the sections the plan must include, with descriptions of what goes in each.
Use the explore guidance to direct your investigation in the next step. Use the template sections to structure the plan in step 6.
5. Investigate the code (the core of the job)
This is where the plan earns its precision. Do not guess.
Spawn the Explore subagent (subagent_type: "Explore") with the explore prompt from the loaded reference file, scoped to the repo resolved in step 1. Do the exploration in the subagent, not inline. This keeps the main context lean and lets the search run without bloating the conversation.
- If the repo uses graphene, read the relevant nodes before exploring files, and record any boundary or gotcha you find.
- Wait for the Explore subagent to return before continuing.
- If it comes back with low-confidence or empty findings (e.g. user described something not in this repo), surface that to the user and confirm the right repo before continuing.
6. Read the files you intend to cite
Before drafting, Read the 3-5 most-cited files from the Explore findings using the Read tool. Quote snippets verbatim from those reads, not from Explore's prose. This is the single largest lever for avoiding accuracy-driven review rounds. Explore summaries are high-level by design, and small inaccuracies (wrong line number, paraphrased identifier, missing helper) compound into multiple HIGH findings when the reviewer cross-checks against the real files.
If you would cite a file you have not read in this skill invocation, read it now. Record git rev-parse HEAD as the base commit. The plan is anchored to it.
7. Reproduce (bugs only)
- Build the smallest reproduction that triggers the failure. Isolate it from unrelated state.
- Capture the exact commands, the observed output verbatim, and the expected output.
- Find the root cause. Mark it "confirmed" only if proven, else "hypothesis".
- Check for regression:
git log/git blameon the affected lines for the introducing commit. - The reproduction goes into the plan as a re-runnable recipe. Do not depend on a scratch dir surviving.
8. Write the plan
Build the full description using the template sections from the loaded reference file. Do not write it to the issue yet.
Every plan starts with:
## Request
> <original ask, verbatim>Then include every section specified in the reference file. Fill placeholders with Explore findings and your own file reads. Do not leave placeholders in the output. Sections marked (optional) should be omitted if no content exists for them rather than left empty.
All plans must have:
Implementation plan: numbered list, each pinned to a file path with symbol names. Each step names the file, the symbol (function, struct, method), and the precise change. Anchor to the symbol plus the base SHA. Line numbers are hints, symbols are the anchor. For new files, state the intended shape and reference an existing file as the pattern to follow.
Reference patterns: existing code the implementation agent should model on, with paths and short quoted snippets. This is what stops the agent from writing code that compiles but doesn't match the codebase's conventions.
Edge cases & error handling: explicit bullet list of cases the implementation must handle.
Testing: specific tests with file paths, scenarios, and assertions. Not "add tests" but the actual cases:
path/to/file.test.ts-- given<input>, when<action>, expect<result>
Acceptance criteria: testable statements, checkboxes. Keep each item free of inline code (no backticks). Use the bare identifier name instead if you need to mention one.
Out of scope: what NOT to touch.
Open questions / assumptions: anything unverified, for the review stage.
9. Self-review loop
Refinement and review run in one warm stage. The investigation context is already loaded, so reviewing and fixing here is far cheaper than handing off to a separate stage that would have to re-investigate from scratch.
Dispatch the plan-reviewer agent (subagent_type: "plan-reviewer") to attack the draft. A fresh subagent with adversarial framing catches issues the author misses. Pass three labelled blocks:
**Plan draft:**
<full description draft>
**Original brief:** <verbatim user request from the issue>
**Repo:** <absolute cwd path>The agent returns Critical/High/Medium/Low findings and a PASS/FAIL verdict.
Post every round's findings as a comment. After each review round, post the agent's full findings (all four buckets and the verdict) to the issue via add_issue_comment before fixing anything. This is the observability trail: it shows what refinement's draft got wrong each pass, which is the signal for improving this skill over time. Do not skip a round's comment, even on PASS.
On FAIL or any Critical/High findings: fix the named issues in the draft, then re-dispatch. Productive iteration is allowed. Keep going as long as each round surfaces new issues, because that means the fixes are working and the reviewer is finding genuinely fresh problems.
When to stop iterating (in order, first matching condition wins):
- PASS or only Medium/Low remain. Apply Medium fixes. Move on.
- Findings recur. Same sections, same gaps, same dimensions as the prior round. Stop thrashing. Surface as
**Unresolved findings:**in the Open questions section. - Hard cap: 4 total reviews. Most plans converge in 1-2. Needing 3-4 is a signal the original brief was thin or the codebase is unfamiliar.
Calibration: the adversarial framing is deliberate. It compensates for "I just wrote this so it must be fine" bias. If the review comes back clean, accept it and move on. Do not push the subagent to invent findings, and do not re-run a passing review hoping for issues.
If something genuinely cannot be fixed from available material (e.g. the template asks for a Telemetry section but Explore returned no telemetry patterns), do not invent content. Note it as **Unresolved:** <what's missing and why> in the Open questions section of the plan.
If the loop hits the hard cap with blocking findings still open, put them in the plan's Open questions section, post a final comment flagging them, and still route to Plan Review. The human decides whether to send it back to Refine Ready or add detail.
10. Preview and confirm (interactive mode only)
Skip this step in pipeline mode. The autonomous agent writes the plan and transitions status without waiting for a human.
In interactive mode, show the user the full plan as it will appear in the issue description. Accept inline edits:
- "drop the out of scope section" -> remove, re-show.
- "change the approach for step 3" -> update, re-show.
- "this is a feature not a bug" -> reclassify, regenerate.
Wait for explicit confirmation before writing. Do not proceed on ambiguous responses.
11. Write the plan and transition status
Write the final converged plan and move the status in one update_issue call: key, description, and status: "Plan Review". Plan Review is its own named status, distinct from the implementation-side Code Review gate, so setting it by name is unambiguous — no group-qualified state ID to resolve first. The description opens with the user's verbatim ask, so nothing is lost when it overwrites the field. The self-review already ran inline (step 9), so the plan moves straight to the human gate. The round-by-round findings are already on the issue as comments.
Rules
- Build the whole plan before writing. One
update_issuecall, not incremental edits. - Preserve the original ask verbatim at the top. The overwrite is why this matters.
- Quote real code from real files. Do not paraphrase snippets. If you would cite a file you have not read, read it first.
- Include reference patterns with quoted snippets so the implementation agent knows what good looks like in this codebase.
- Exact over vague. If you cannot name the symbol and the change, you have not finished investigating.
- Separate fact from hypothesis. The review stage attacks the assumptions, so make them visible.
- Name specific test cases with file paths, scenarios, and assertions. "Add tests" is not a test plan.
- For any runtime/behavioural acceptance criterion, name an EXERCISING test, an integration test against the mock CLI (see the integration-test skill) or a spawn-arg unit test, not just a helper unit test. A criterion that can only be proven by running the feature needs a test that runs it.
- A load-bearing assumption (one the feature's behaviour depends on, e.g. "the CLI reports the injected server under this name, which the permission filter keys on") must become a specific test or a runtime check in the plan, not sit in Open Questions as prose. An unverified assumption on a critical path is how a feature ships dead.
- A "render / display X readably" criterion must specify the CONCRETE expected output per field, not just "readable". Name what each value should look like (a schedule shows as
Cron: 0 2 * * *, never JSON; a long prompt shows as a block) and state "no raw JSON in user-facing output" when that is the intent. "Readable display" alone makes the implementer and the reviewers guess, and they guess wrong (ALE-617: the code-reviewer's reasonable-lookingJSON.stringifyfix produced the exact JSON the user kept rejecting). - Any UI rendering criterion must hold in BOTH light and dark themes — say so explicitly. Syntax-highlight / markdown / code components are a known dark-mode trap (they can hardcode a light theme and go invisible).
- When a change touches a surface meant to mirror another (an MCP tool that should expose the same fields as a UI form; two views of the same data), make that PARITY an explicit acceptance criterion and enumerate the fields. A "like-for-like with the UI" requirement that is only implied gets missed (ALE-617: the job MCP tools were missing runtime / allowedTools / mcpServers / mcpToolFilters / notifyProviders / schedules; the user found it only by testing).
- Ambiguous scope (which sessions / surfaces / users does this apply to?) becomes an Open Question for the human, and the plan defaults to the NARROWER interpretation — never silently pick the reading that touches more surface (ALE-617: "block bypass" was refined as all interactive sessions; the user had to bounce it back to cockpit-agent-only).
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

