# Sks Issue Refine

> Use when iterating a problem to convergence inside its GitHub issue via research and comments before deriving the PR.

- Skill: `shikanime-labs/sks-issue-refine` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx skillmds@latest add shikanime-labs/sks-issue-refine`
- Raw SKILL.md: https://api.skillmd.com/api/skills/shikanime-labs/sks-issue-refine/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Research & Search
- License: Apache-2.0
- Author: shikanime-labs (https://skillmd.com/u/shikanime-labs)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/shikanime-labs/sks-issue-refine

---


# Shikanime Issue Refinement

The issue IS the problem statement. `sks-issue` opens it (body = problem
statement + `- [ ]` gate ledger + References); conclusions are posted as issue
comments. This skill is the **iteration loop**: resolve an existing issue's open
questions via research + candidate solutions until the problem statement and
acceptance criteria converge (wayfinder's fog cycle on the thread).

## When to Use

- Issue exists (`sks-issue`) but the problem is still foggy.
- NOT for opening/RFC/edge — `sks-issue`/`sks-discussion`; open once it
  converges into a statable problem.
- NOT for implementation (`sks-pr`/branch phase). Refine writes comments, never
  product code.

## Model: the issue comment thread is the iteration space

- **Destination** — the converged problem statement the body should hold.
- **Fog of war** — questions you can state but not answer; research until
  precise, then resolve.
- **Frontier** — open resolvable questions; clear one at a time.
- **Four question kinds** (only `research` fans out; `grilling` is strictly
  serial with the human):

  | Kind        | Mode   | Use when                                                      | Resolved by                                                    |
  | ----------- | ------ | ------------------------------------------------------------- | -------------------------------------------------------------- |
  | `research`  | AFK    | A fact outside the working dir blocks a decision.             | A `delegate_task` agent; findings posted as a comment.         |
  | `prototype` | HITL   | "How should this look/behave" — talk can't settle it.         | A cheap artifact (linked); **selection stays with the human**. |
  | `grilling`  | HITL   | The default — settleable by talking it through.               | Precise one-at-a-time questions, _why_ attached.               |
  | `task`      | Either | No decision, but manual work (access, data shape) blocks one. | A precise checklist — never product code.                      |

## Procedure

1. **Load** — `gh issue view <N>`; read body + comments. If the problem can't
   yet be stated, route to `sks-discussion`.
2. **Enumerate the fog** — one line per open question in your in-agent
   scratchpad (never post raw).
3. **Classify** each question into one of the four kinds.
4. **Resolve AFK in parallel** — `research` fans out via `delegate_task` (one
   child per independent fact; isolate on `research/<name>` per `sks-async` if
   it touches the repo; read-only, never edits product code — see
   `references/delegate-research.md`). `grilling`/`prototype` engage the human
   serially — one question, wait, next.
5. **Post only the conclusion as a comment** — each resolution is a single
   `gh issue comment` stating the decision reached, nothing more. No finding
   dumps, candidate lists, or reference trails; body stays the stable problem
   statement. Durable References move into the body via `gh issue edit`. Keep
   any reply to the human short and on-point. Comment shape: decision first,
   evidence second (diff lines or command output), nothing else — one
   resolution per comment, no nested parentheticals, asides become sentences.
6. **Convergence test** — stop when: no item reads "build the X"; fog clears;
   body is a clean problem statement + decidable `- [ ]` ledger.
7. **Hand off** — route to `sks-pr`/branch phase (`sks-dev-workflow` phase 3+).
   Never carry implementation into this loop.

## Pitfalls

- Writing product code — `task` only unblocks a decision, never delivers a slice
  of the destination.
- Fog as a ticket — "investigate X" with no precise question isn't a question;
  research it, then phrase the real one.
- Parallel grilling — serial only; two threads ask the same thing in different
  words. Only `research` fans out.
- Prototype self-selection — agent builds variants and picks one → broken
  ticket; the human chooses, the agent links artifacts.
- Editing the body with findings — findings stay in comments; only durable
  References may move into the body.
- Leaking the thinking — fog drafts, classification, status chatter stay
  in-agent; the thread gets only the resolved comment. Interim comments
  deletable once converged.
- English only — no French; do not carry cpn templates in.

## Verification

```bash
gh issue view <N> --repo <org>/<repo> --json number,title,comments
```

Every open question has a resolution comment; body holds a problem statement +
References only; convergence passes before `sks-pr` handoff.

## References

- `references/wayfinder-distillation.md` — wayfinder distillation (four kinds,
  plan-don't-build, failure modes).
- `references/delegate-research.md` — `delegate_task` fan-out snippet +
  read-only/report contract.

## See also

- `sks-issue` — opens the iterated issue.
- `sks-discussion` — RFC/edge; use before problem is statable.
- `sks-pr` — solver; links back via `Related:`.
- `sks-async` — isolation for parallel `research` fan-out.
- `sks-issue-triage` — assign metadata once converged.
- `sks-investigate` — defect root-cause research; use it when the issue is a
  diagnosed bug needing its cause, not a foggy problem needing framing.