Baonguyen/sprint refinement

.github/ISSUE_TEMPLATE/bug.md

@@ -9,6 +9,8 @@ labels: bug
 
 - [ ] Reviewed by human engineer
 - [ ] Issue refinement complete
+- [ ] All open questions answered
+- [ ] Post-refinement changes reviewed by human
 - [ ] Ready for work
 
 ## What happened

.github/ISSUE_TEMPLATE/chore.md

@@ -9,6 +9,8 @@ labels: chore
 
 - [ ] Reviewed by human engineer
 - [ ] Issue refinement complete
+- [ ] All open questions answered
+- [ ] Post-refinement changes reviewed by human
 - [ ] Ready for work
 
 ## What and why

.github/ISSUE_TEMPLATE/epic.md

@@ -9,6 +9,8 @@ labels: epic
 
 - [ ] Reviewed by human engineer
 - [ ] Issue refinement complete
+- [ ] All open questions answered
+- [ ] Post-refinement changes reviewed by human
 - [ ] Ready for work
 
 ## Goal

.github/ISSUE_TEMPLATE/spike.md

@@ -9,6 +9,8 @@ labels: spike
 
 - [ ] Reviewed by human engineer
 - [ ] Issue refinement complete
+- [ ] All open questions answered
+- [ ] Post-refinement changes reviewed by human
 - [ ] Ready for work
 
 ## Question to answer

.github/ISSUE_TEMPLATE/story.md

@@ -9,6 +9,8 @@ labels: story
 
 - [ ] Reviewed by human engineer
 - [ ] Issue refinement complete
+- [ ] All open questions answered
+- [ ] Post-refinement changes reviewed by human
 - [ ] Ready for work
 
 ## What and why

.github/ISSUE_TEMPLATE/technical-task.md

@@ -9,6 +9,8 @@ labels: technical-task
 
 - [ ] Reviewed by human engineer
 - [ ] Issue refinement complete
+- [ ] All open questions answered
+- [ ] Post-refinement changes reviewed by human
 - [ ] Ready for work
 
 ## What we decided

AGENTS.md

@@ -94,10 +94,12 @@ For `technical-task.md`, fill "Starting point" and "Constraints and gotchas" tho
 what an agent or new developer needs to pick up work cold.
 
 The `create-issue` skill guides checking for duplicates, choosing the template, wording, labeling, reviewing, and filing.
+After initial human review, the `refine-issue` skill pressure-tests an existing issue for sprint
+readiness.
 
 ## Architecture and CI
 
-Deep reference lives in two rule files under `rules/` at the repo root. Claude Code auto-loads each
+Deep reference lives in rule files under `rules/` at the repo root. Claude Code auto-loads each
 when you touch a path its `paths:` frontmatter matches; other tools do not, so open the relevant file
 directly when working the paths noted below.
 
@@ -106,6 +108,8 @@ directly when working the paths noted below.
   `skills/generate-strata-docs/`, or anything under `docs/`.
 - `rules/ci.md`: the lint pipeline and the doc-generation workflows. Applies when editing
   `.github/workflows/` or doc frontmatter.
+- `rules/subagent-model-tiers.md`: which Claude model to give a sub-agent that a skill dispatches
+  via the `Agent`/Task tool. Applies when editing anything under `skills/`.
 
 ## Conventions and gotchas
 

CONTRIBUTING.md

@@ -6,8 +6,12 @@ The short version of how a change moves through this repo:
 
 1. **Start from an issue.** File one with the template that fits the work (epic, story, bug,
    technical-task, spike, or chore). The `create-issue` skill walks you through checking for
-   duplicates, choosing a template, wording it for its audience, reviewing it, labeling it, and
-   filing it.
+   duplicates, choosing a template, wording it for its audience, reviewing it, labeling it, and filing it.
+   Every template opens with an "Issue readiness state" checklist that tracks the issue's lifecycle: reviewed by a human
+   engineer, refinement complete, all open questions answered, post-refinement changes reviewed by
+   a human, and ready for work. Tick the boxes as the issue advances; the `refine-issue` skill
+   manages the middle three and requires the initial human review (at least one human comment on
+   the issue) before it will run.
 2. **Branch.** Use the naming shape in [Branching](#branching) below.
 3. **Make your changes.** Keep commits terse and explain why, not what. Wire up the commit template
    (see [Commit message template](#commit-message-template)).

rules/subagent-model-tiers.md

@@ -0,0 +1,22 @@
+---
+paths:
+  - "skills/**"
+---
+
+# Sub-agent model tiers
+
+Which Claude model to give a sub-agent when a skill dispatches one via the `Agent`/Task tool.
+Auto-loaded by Claude Code when you edit anything under `skills/`. Choose by the kind of work the
+sub-agent does. This rule covers model choice only, not effort level.
+
+- **Tier 1, Opus.** Sub-agents that reason at length, hold large context, ask probing questions,
+  debate, or make thoughtful judgment calls. Examples: a product-versus-engineering debate,
+  reviewing a draft against its sources, adjudicating whether a change is warranted.
+- **Tier 2, Sonnet.** Sub-agents doing everyday, well-scoped work: synthesis, drafting from an
+  already-decided set of inputs, routine transforms.
+- **Tier 3, Haiku.** Sub-agents that only execute an already-decided plan, following instructions
+  authored by a higher tier. No open-ended reasoning.
+
+In practice: `review-draft` keeps its parallel reviewers on a cheap tier and its adjudication in a
+more capable model; `refine-issue` runs its debate, review, and adjudication roles on Opus and its
+planner on Sonnet. Neither skill sets effort.

skills/refine-issue/SKILL.md

@@ -0,0 +1,225 @@
+---
+name: refine-issue
+description: Refines an existing GitHub issue for sprint readiness by running a product-owner versus senior-engineer debate over it, reconciling human comments, adjudicating every proposed change, and updating the issue via gh only after you approve. Use to pressure-test an issue's goals, scope, and feasibility before a team commits to it in a sprint.
+---
+
+# Refine Issue
+
+Takes one existing GitHub issue and pressure-tests it before a sprint commits to it. This skill is
+an orchestrator: it dispatches sub-agents that debate the issue, reconciles the human comments
+already on it, adjudicates each proposed change, plans a refined issue, and updates the issue via
+`gh` only after you approve. It runs entirely in this file using the `Agent`/Task tool. It does not
+use the `Workflow` tool. Sub-agents never talk to the user; only you, the orchestrator, do, at the
+approval gate.
+
+## When to use
+
+Use on an existing issue that is about to enter a sprint and needs sharpening: unclear goals, fuzzy
+scope, unstated acceptance criteria, or unverified technical feasibility. Skip it for a throwaway or
+an already-refined issue.
+
+The issue must already have an initial human review: at least one human comment on it, even a bare
+"looks good to me". The skill will not run the debate on an unreviewed issue (see Step 2).
+
+You need the issue number or URL and write access via `gh`.
+
+## Model tiers
+
+Dispatch each role with the model named below, per `rules/subagent-model-tiers.md`:
+
+- Product Owner, Senior Engineer, Reviewer, Adjudicator: Opus (they reason, debate, and judge).
+- Planner: Sonnet (it assembles an already-decided result).
+
+Dispatch each role as a `general-purpose` agent, setting the `model` param. Effort is not set.
+
+## Roles
+
+Each role's full instructions are below. When you dispatch a role, inline that role's instructions,
+the issue (title, body, comments), and the running debate transcript into the sub-agent's prompt.
+Every role ends its reply with a structured findings list, described under its heading. Roles return
+data, not prose for the user.
+
+### Product Owner (Opus)
+
+You are the product owner. Bring the goals, the whys and the whats, and the user value. Your job is
+to make the issue express the outcome it should achieve and why it matters, not how to build it.
+
+Do:
+- State the user or business outcome the issue should deliver, and who benefits.
+- Turn vague requirements into concrete, testable acceptance criteria.
+- Push for scope that serves the outcome; call out gold-plating and missing must-haves.
+- Respond to the senior engineer's prior turn in the transcript: concede good points, defend the
+  ones that matter for user value.
+
+Do not specify implementation, estimate effort, or let scope creep pass unchallenged.
+
+End your reply with a list of proposed changes and open questions. For each proposed change give:
+origin (product-owner); target (title, body-section, acceptance-criteria, or open-question); current
+(what the issue says now, or "none"); proposed (the new text); rationale (why). Then list any probing
+questions you could not answer from the issue alone.
+
+### Senior Engineer (Opus)
+
+You are the senior engineer. Argue back. Your job is to make sure the issue is technically sound,
+feasible, and complete enough to build.
+
+Do:
+- Ask probing technical questions the issue leaves unanswered (data, interfaces, dependencies, edge
+  cases, non-functional needs).
+- Test feasibility: is what the product owner wants buildable as stated, and at what cost or risk?
+- Surface hidden complexity, unknowns, and dependencies on other work.
+- Respond to the product owner's prior turn in the transcript: challenge assumptions, propose
+  sharper criteria, or agree where they are right.
+
+Do not redesign the whole thing or block on perfection. Aim for buildable and clear.
+
+End your reply with the same structured list: proposed changes (origin senior-engineer, with target,
+current, proposed, rationale) and probing questions you could not resolve.
+
+### Reviewer (Opus)
+
+You are the reviewer. You have the issue, its comments, and the full debate transcript. Weight the
+issue's existing human comments heavily: humans commented for a reason, and their intent must not be
+lost in the refinement.
+
+Do:
+- Identify every human comment and what it asks for; check that the debate did not contradict or
+  ignore it.
+- Flag conflicts between the debate's proposed changes and what humans said.
+- Add or adjust proposed changes so the refined issue honors the human comments.
+
+End your reply with a list of proposed changes (origin reviewer, same fields) and a list of conflicts
+you found (each: the human comment, the proposed change it conflicts with, and your recommendation).
+
+### Adjudicator (Opus)
+
+You are the adjudicator. You have the issue and every proposed change from the product owner, senior
+engineer, and reviewer. Decide each on its merits by re-checking it against the issue. Do not accept
+changes blindly.
+
+For each proposed change, return a verdict: accept or reject, plus a why. Reject a change that is
+wrong, out of scope, contradicts a human comment, or is not supported by the issue's intent, and say
+so. Keep the changes in the order given.
+
+End your reply with the verdict list, one entry per proposed change, in order.
+
+### Planner (Sonnet)
+
+You are the planner. You have the issue and only the accepted changes. Assemble the refined issue.
+Change nothing that was not accepted.
+
+Produce:
+- refined_title: the issue title, unchanged unless a change targeted it.
+- refined_body: the full refined issue body in GitHub markdown, one line per paragraph (no hard
+  wrapping), no em dashes. Fold the accepted changes into the existing structure. Add an "Open
+  Questions" section listing every unresolved probing question.
+- change_summary: a short markdown summary of what changed and why, for a comment on the issue.
+- open_questions: the list of unresolved questions, also embedded in the body.
+
+Readiness block rules:
+- Preserve the "Issue readiness state" section at the top of the refined body, keeping its checkbox
+  list intact and in order. If the issue predates the block, insert the current five-state block
+  from the repo's issue templates (`.github/ISSUE_TEMPLATE/`).
+- Set the boxes to reflect this refinement: tick "Issue refinement complete"; tick "All open
+  questions answered" only when the Open Questions section is empty; leave "Post-refinement changes
+  reviewed by human" unticked, since the skill's edits always need a fresh human look; never tick
+  "Ready for work". Leave "Reviewed by human engineer" as you found it.
+
+Write the body as if authored fresh. No change narrative or meta-commentary: nothing like "this
+replaces the earlier framing", "not a fixed requirement", or defensive clarifications about what
+counts as in scope. What changed and why belongs only in change_summary.
+
+End your reply with these four fields, each clearly labeled.
+
+## Steps
+
+### 1. Fetch the issue
+
+Read the issue and its comments:
+
+```bash
+gh issue view <number> --json number,title,body,comments,labels,author,url
+```
+
+Note which comments are human-authored (the comment author is not a bot). Keep the full issue and
+comments as context for every dispatch.
+
+### 2. Gate on an initial human review
+
+Refinement builds on a human's read of the issue, so require one before dispatching anything:
+
+- If the issue has at least one human-authored comment, proceed. A bare "looks good to me" counts;
+  it shows a person read the issue. If the body has an "Issue readiness state" block, also note
+  whether "Reviewed by human engineer" is ticked, and carry that state through unchanged.
+- If it has none, stop the pipeline and tell the user the issue has not had an initial human
+  review. Offer exactly two paths: the user supplies their feedback now, which you post to the
+  issue with `gh issue comment` and then treat as the human review and proceed; or the run ends
+  here. Never run the debate on an unreviewed issue.
+
+### 3. Run the debate loop
+
+Run a bounded debate, default 2 rounds. Maintain a shared transcript holding each turn's argument
+and its proposed changes. Each round:
+
+1. Dispatch the Product Owner (Opus, general-purpose), inlining the Product Owner instructions, the
+   issue, the comments, and the transcript so far. Append its output to the transcript.
+2. Dispatch the Senior Engineer (Opus, general-purpose) the same way, including the Product Owner's
+   turn. Append its output to the transcript.
+
+After the last round, collect every proposed change from both roles.
+
+### 4. Reconcile with human comments
+
+Dispatch the Reviewer (Opus, general-purpose) with the issue, the comments, and the full transcript.
+Add its proposed changes to the collected set. Carry its conflict list forward: pass it to the
+Adjudicator in Step 5, and surface any conflict that stays unresolved at the gate in Step 8 so
+nothing is dropped silently.
+
+### 5. Adjudicate
+
+Dispatch the Adjudicator (Opus, general-purpose) with the issue, the full set of proposed changes,
+and the Reviewer's conflict list. Collect a verdict per change. Keep the accepted set, the rejected
+set with reasons, and any conflict the adjudication left unresolved.
+
+### 6. Plan the refined issue
+
+Dispatch the Planner (Sonnet, general-purpose) with the issue and the accepted changes only. Collect
+refined_title, refined_body, change_summary, and open_questions.
+
+### 7. Style-check the body
+
+Run the `review-draft` skill on refined_body as an issue draft. Apply the findings you accept. This
+enforces house style, no em dashes, and no hard-wrapped paragraphs.
+
+### 8. Present and ask permission
+
+Show the user the refined title and body, the change summary, the open questions, every rejected
+change with its reason, and any unresolved human-comment conflict. Ask for explicit permission to
+apply the changes to the issue. Do not write anything yet.
+
+### 9. Apply, only after approval
+
+On approval, write the refined body and the summary to temporary files and run:
+
+```bash
+gh issue edit <number> --title "<refined_title>" --body-file <body.md>
+gh issue comment <number> --body-file <summary.md>
+```
+
+Pass the body and comment via files so multi-line markdown survives the shell. The summary comment
+must end by reminding the reader that "Post-refinement changes reviewed by human" is unticked and
+awaiting them. On denial, write nothing and stop.
+
+## Notes
+
+- Sub-agents never talk to the user. Only the orchestrator prompts, at the Step 2 gate and at
+  Step 8.
+- Never drop a finding silently: rejected changes are shown with reasons, and unresolved questions
+  become an Open Questions section in the body and are surfaced at the gate.
+- The "Issue readiness state" block is never dropped, reordered, or rewritten away; treat it like
+  the pipeline's "never silently drop" invariant. The Planner's readiness block rules say which
+  boxes to tick.
+- If a sub-agent's output is unreadable, re-dispatch it once, then surface the failure rather than
+  guessing.
+- This skill complements `create-issue`, which files new issues, and reuses `review-draft` for the
+  style pass.