Skip to content

tibursocampos/agent-dev-toolkit / core/skills/refine-story

refine-story

Verified

Refine a Bug, User Story, or Technical Story into structured markdown with BDD acceptance and a quality scorecard. Use when refining backlog or invoking /refine-story.

references/feature-research.md

View on GitHub
# Feature research cycle

Load when `invocation_context=orchestrated` and refine mode is `feature`. Direct invocation uses the mode playbook in `feature.md` and does not start this cycle unless the parent already set the mode.

Skill prose in this file is English. Questions shown to the user, and prose written into `FEATURE.md`, follow the chat language (`LANGUAGE.md`). Tokens stay English.

Do not create a separate clarification artifact. Section updates land on `FEATURE.md` (macro acceptance, decisions, open questions). When a story folder already exists, decision history for that story stays in `references/qa-history.md`.

Companion: `finding-format.md`, `readiness-severity.md` § Open-question gate, `spawn-map.md`, `persona-context.md`.

## Fixed order

1. Read `FEATURE.md`. Read `memory-bank/` only when that bank exists. Do not dump the bank (`SELECTIVE-RETRIEVAL.md`).
2. Call specialists only as `orchestrate-analyze/references/spawn-map.md` maps `needs_*`. Do not invent extra roles. Take specialist returns in the parent. Do not create story folders in this cycle.
3. First findings pass. Record each finding with `finding-format.md`.
4. Second pass, isolated from the first. When an Agent tool is available, the two passes do not see each other's notes until both finish. When Agent is unavailable, finish pass one, then run pass two in the same context and say that the passes were not isolated.
5. Close a finding only when it has a portable evidence path or an explicit user answer. `no-evidence` stays open.
6. Ask every remaining open question in one batch. Include `MINOR`. Do not ask only `B` and `I`.
7. Stop when no open question remains, or after two critique rounds, whichever comes first. If any question is still unanswered when the round ceiling is hit, stop with `open_question`. That is not a clean finish.

A critique round is one pair of isolated passes plus the single question batch that follows. Do not invent a finding to force another round. Two rounds is the ceiling.

When O1 step 8c runs, the stage table from `LIVE-STAGE-TABLE.md` must be shown for both rounds. A second round adds no row: it returns the rows `First findings pass` through `One question batch` to `in_progress` one at a time, and notes `round 2` in `what_happened`. Redraw the full table at each change.

## Inspection list

Check the FEATURE for:

- Actor
- Goal
- Scope
- Precondition
- Main flow
- Error flow
- Permission
- Data owner
- Integration
- Acceptance criterion with an observable condition and a failure
- Undefined term
- Empty behavior

Severity, impact, and owner (`Product`, `Engineering`, `UX`) follow `finding-format.md` and the Open questions table on `FEATURE.md`.

## What to ask

Ask product decisions the FEATURE does not already answer.

Do not ask for a class path, file path, or route when that is a technical follow-up the repository can answer. Record that follow-up for the specialist or later spec. It does not close a functional question, and it does not replace one.

## Persona pass

The persona pass applies only to a User Story or a Bug. Load `persona-context.md` only. Use role and job. Do not invent a person's name. Do not run the persona pass for a Technical Story.

## History

Research before asking. One batch of questions per round. Repeat until no open question remains, or the two-round ceiling is hit. A ceiling hit with an unanswered question is `open_question`, not approval to create story folders.

Preserve existing `question_id` and `decision_id` values in `FEATURE.md`; allocate the next unused stable IDs for new questions and decisions, and never recycle an ID. Keep the feature-level Decisions/Open questions in `FEATURE.md`. When a finding or decision affects a story that already exists, record its question → decision → affected artifact/section links, including applicable REQ/CA IDs, in that story's one canonical `qa-history.md` location as defined by `qa-history.md`. Reuse the existing history path and IDs; if it has not yet been persisted, carry the same IDs and impact links into it when first saved. Do not create a second clarification or decision-history artifact. Do not delete a prior decision to make a file shorter; mark replaced decisions superseded and link the replacement in the existing history.
slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 198kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 194kUpdated Claude CodeCodexVerifiedInstall