xiduzo/wtf/wtf-refine

Refine

Update an existing Epic, Feature, or Trace issue from new insights.

This skill merges insights from any source. It finds which sections change. It re-runs only the validations those changes need. It shows a precise diff before it writes. It cascades scenario edits to claiming Traces so nothing goes stale.

This skill is also the single Re-aim mechanism. After a Trace lands, the Feature's Trace Plan absorbs what the Trace revealed. It has two entry points. A human runs it interactively. wtf.loop runs it headlessly after each verified Trace — see Headless mode at the end of this file.

Process

0. GitHub CLI setup

Run steps 1–2 of ../references/gh-setup.md (install check and auth check). Stop if gh is not installed or not authenticated. Note whether the extensions are available. They are used in step 1 (hierarchy fetch) and step 9 (cascade).

Skip this step if gh-setup was already confirmed this session.

1. Identify the issue and its hierarchy

If an issue number was passed in as context or a CLI argument, use it directly. Otherwise call AskUserQuestion (per ../references/questioning-style.md):

• question: "Which issue are you refining?"
• header: "Issue"
• options: from recently-updated open issues across all WTF kinds (epic, feature, trace — plus legacy task), inferred from:

# Resolve $WTF_CLASS once — see ../references/issue-classification.md.
if [ "$WTF_CLASS" = types ]; then
  gh issue list --search 'state:open (type:"Epic" OR type:"Feature" OR type:"Trace" OR type:"Task")' --json number,title --limit 10
else
  gh issue list --search 'state:open (label:epic OR label:feature OR label:trace OR label:task)' --json number,title,labels --limit 10
fi

Fetch the issue:

gh issue view <issue_number> --json number,title,body,labels,comments,updatedAt

Detect the issue kind — follow the Detect the kind of an existing issue block in ../references/issue-classification.md. It reads the native issue type in types mode and the kind label in labels mode. Compare case-insensitively:

• Epic → kind = Epic
• Feature → kind = Feature
• Trace → kind = Trace
• Task → kind = legacy Trace. Tell the user that this is a legacy Task issue and that you treat it as a legacy Trace. Route it through the Trace validation path. A legacy Trace carries its own canonical Gherkin in its body. The scenario canonicality guard (step 3) does not apply to it.
• Indeterminate (no type set and no kind label) → call AskUserQuestion (per ../references/questioning-style.md):
• question: "I couldn't detect the kind of this issue. What kind is it?"
• header: "Issue kind"
• options: Epic / Feature / Trace

Fetch the hierarchy for context and cascade planning:

# Parent (always fetch — needed for context)
gh sub-issue list <issue_number> --relation parent
 
# Children (needed for cascade planning in step 9)
gh sub-issue list <issue_number>

For the parent issue, fetch its body. Extract goal, bounded context, and success metrics. These show whether a child change conflicts with the parent intent.

If the issue is a Trace, the parent Feature body also holds the canonical scenarios and the Trace Plan. Keep it at hand for steps 3–4.

2. Gather insights from all sources

Merge insights from every available source into one list. Process all sources in parallel:

a. CLI argument / conversation context

If the user passed insight text in the invocation (e.g. refine #42 "scope changed — exclude mobile"), treat that as the primary insight. If the insight is a landed Trace (e.g. re-aim feature #24 after trace #57), read the landed Trace issue. Its Revealed learnings, verify results, and PR link are the insight sources. If nothing was passed, call AskUserQuestion (per ../references/questioning-style.md):

• question: "What changed or what new insight should I incorporate?"
• header: "Insight"
• options: from plausible changes inferred from recent issue comments (e.g. the last comment's key point)

b. GitHub comments since the last refinement

Extract comments posted after the last audit-trail comment this skill posted (a comment whose body starts with ## Refinement — or ## Re-aim (headless)). If no such comment exists, fall back to the issue's createdAt. Do not compare against updatedAt — that is the issue's last activity, comments included, so nothing would ever match:

gh issue view <issue_number> --json createdAt,comments \
  --jq '(.createdAt) as $c0 | ([.comments[] | select(.body | test("^## (Refinement|Re-aim \\(headless\\)) —")) | .createdAt] | max // $c0) as $since | .comments[] | select(.createdAt > $since) | "[\(.author.login)] \(.body)"'

Read each comment. Extract actionable insights. Discard discussion noise ("+1", "agreed", "thanks"). Synthesise into concrete change signals (e.g. "Stakeholder comment: settlement must support multi-currency").

c. Referenced files

If the user referenced any file paths or URLs in the CLI argument or conversation, read them now:

• File paths → use the Read tool
• URLs → use the WebFetch tool (if available) or ask the user to paste the relevant content

Extract the relevant change signals from each document.

d. Consolidate

Merge all signals into a numbered list of insights. Present them briefly to the user:

"I found [n] insight(s) to incorporate:

1. [insight summary]

2. [insight summary]

..."

Call AskUserQuestion (per ../references/questioning-style.md):

• question: "Does this capture everything you want to incorporate?"
• header: "Insights"
• options:
• Yes — proceed → continue with these insights
• Add more → I have additional context to provide
• Remove one → some of these are not relevant

Apply any adjustments before you continue.

3. Classify the changes

For each insight, determine which sections of the issue it affects. Also determine what type of change it is. This classification drives which validations run in step 4. It also drives which sections are rewritten in step 5.

Change types and their affected sections:

Notes on the Trace column:

• A Trace has no canonical Gherkin of its own. Scenario-text changes happen on the Feature. A Trace-level refinement touches its Scenario Claim (which scenarios it names), Spine Position, Contracts, and Technical Approach.
• Scenarios and Trace Plan are Feature sections. A scenario edit on a Feature cascades to every Trace whose Scenario Claim names it (step 9): the synced courtesy copy is refreshed and stale lifecycle labels are stripped.
• Legacy Trace: map the Trace column onto its legacy sections — Gherkin, Functional Description, Contracts, Technical Approach. Its body is canonical for its own Gherkin. Edit the Gherkin in place.

Trace landed — re-aim. The landed Trace's learnings re-aim the remaining plan. Affected section: the Feature's Trace Plan. Allowed moves: reorder the remaining entries, re-batch them, and move scenarios between remaining entries whose Traces carry neither implemented nor verified. Adding a newly discovered scenario, and any drop, is a set change. Interactive mode shows it in the diff for approval. Headless mode proposes it (see Headless mode) and never applies it. Landed entries — checked, or whose Trace carries implemented or verified — stay untouched. Validation: the partition re-check in step 4.

Scenario canonicality guard. If an insight would edit scenario text on a Trace — the synced <details> copy — stop. That copy is a courtesy projection. The canonical scenarios live on the parent Feature. Call AskUserQuestion (per ../references/questioning-style.md):

• question: "This change edits scenario text, which is canonical on Feature #<n>. How should I proceed?"
• header: "Canonical scenarios"
• options:
• Refine the Feature → re-target this refinement at the parent Feature. The cascade (step 9) then refreshes this Trace's synced copy. (default)
• Edit the claim only → the change is which scenarios this Trace claims (names), not their text
• Cancel → exit without changes

Exception: legacy Traces hold their own Gherkin — the guard does not fire for them.

Produce a change map — a structured internal summary:

Change map:
  scope changed:        yes
  DDD language changed: no
  ACs changed:          yes
  Scenarios affected:   yes  (canonical on the Feature — because ACs changed)
  Trace Plan affected:  yes  (claims may need re-partition)
  Contracts affected:   no
  Sections to rewrite:  [Goal, Success Metrics] / [User Stories, ACs, Scenarios, Edge Cases, Trace Plan] / [Scenario Claim, Contracts]

4. Re-run relevant validations only

Using the change map from step 3, run only the validations that apply. Skip the rest. Do not re-validate unchanged sections.

Scope changed → Vertical slice + Scope gate

Re-run both stages defined in ../references/scope-gates.md on the refined intent, then on the rewritten sections. The per-level split signals live in the matching write-* skill:

• Epic → wtf.write-epic step 7
• Feature → wtf.write-feature step 9
• Trace → wtf.write-trace

A Trace split is by depth — a Skeleton plus Deepening Traces — never by layer. If a split signal fires on the refined issue, present it as a refinement concern (not a blocker). Use the same keep / split / stop ask the write-* skill uses (see ../references/scope-gates.md).

Domain language changed → DDD Language Guard

Re-run the checks from ../references/ddd-writing-rules.md on any section whose text is being rewritten. Flag and correct violations silently. Note corrections in the diff (step 5).

Apply strict STE per ../references/ste-writing.md before writing any durable body (rewritten sections and the audit trail comment).

ACs changed (Feature) → Scenario re-derivation

The scenarios are canonical on the Feature, so re-derive them here. Re-derive only the scenarios that map to the changed AC(s). Keep unchanged scenarios exactly as they are. Mark the Trace Plan as potentially stale. Traces whose Scenario Claims name a changed scenario become cascade items (step 9). For a legacy Trace, re-derive its in-body Gherkin the same way. In headless mode a re-derivation that adds or removes a scenario is a set change — propose it, do not apply it (Scenario-set gate).

Scenario Claim changed (Trace) → Claim re-check

Verify that every claimed name exists on the parent Feature's story. Verify that the story's claims across all its Traces still cover its scenarios exactly once — full cover, no overlap.

Trace landed — re-aim → Partition re-check

After the Trace Plan rewrite, verify:

1. The remaining claims plus the landed Traces' claims cover each story's scenarios exactly once — full cover, no overlap.
2. The plan has exactly one Skeleton.
3. Every story other than the Skeleton's story keeps exactly one Extension entry, before that story's Deepening entries.
4. The spine order is sound — every entry builds on landed Traces or on earlier entries.