agentleFS
alexjbarnesalexjbarnes/cockpit/.claude/skills/refine-issue/SKILL.md

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

  • Other versions2 projects use a version of this.

    Word for word · 0

    None found.

    Edited · 0

    None found.

    Wrote their own version · 2

    1. TitusKirch/skills★ 2same name
    2. 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.

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
  1. Very specific:

    If the description or a comment links an image, view it directly from its URL.

    line 27
  2. Distinctive:

    Do not ask follow-up clarifying questions yet.

    line 29
  3. Distinctive:

    Before doing any investigation, verify the issue has enough basic information to produce a useful plan.

    line 33
  4. Very specific:

    Add a comment via add_issue_comment listing exactly what is missing and what the reporter should add.

    line 41
  5. Distinctive:

    Stop. Do not proceed with refinement.

    line 42
  6. Very specific:

    bug / regression: use the bug template from references/bug.md.

    line 52
  7. Very specific:

    feature: use the feature template from references/feature.md.

    line 53
  8. Distinctive:

    chore / refactor / task: use the feature template but drop UI-specific and telemetry sections.

    line 54
  9. Very specific:

    Read the reference file for the classified type (relative to this SKILL.md):

    line 59
  10. Distinctive:

    Use the explore guidance to direct your investigation in the next step.

    line 67
  11. Distinctive:

    If the repo uses graphene, read the relevant nodes before exploring files, and record any boundary or gotcha you find.

    line 74
  12. Distinctive:

    Wait for the Explore subagent to return before continuing.

    line 75
  13. Distinctive:

    If it comes back with low-confidence or empty findings (e.g.

    line 76
  14. Distinctive:

    If you would cite a file you have not read in this skill invocation, read it now.

    line 82
  15. Distinctive:

    Check for regression: git log / git blame on the affected lines for the introducing commit.

    line 88
  16. Distinctive:

    Every plan starts with:

    line 94
  17. Distinctive:

    All plans must have:

    line 103
  18. Distinctive:

    Wait for explicit confirmation before writing.

    line 162

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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 Ready and 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_issue for 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's projectId, and use that project's repoPath if 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_issue are 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:

  1. Set the issue status to Needs Detail via update_issue (key + status).
  2. Add a comment via add_issue_comment listing exactly what is missing and what the reporter should add.
  3. 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:

  1. Set the issue status to Refining via update_issue (key + status).
  2. 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.md for bugs and regressions
  • references/feature.md for 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 blame on 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):

  1. PASS or only Medium/Low remain. Apply Medium fixes. Move on.
  2. Findings recur. Same sections, same gaps, same dimensions as the prior round. Stop thrashing. Surface as **Unresolved findings:** in the Open questions section.
  3. 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_issue call, 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-looking JSON.stringify fix 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).

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.