story-clarifier

name

story-clarifier

description

Draft, synthesize, rewrite, tighten, or split rough tickets, conversations, user stories, feature definitions, and acceptance criteria into testable story cards or split story sets, or audit existing story inputs with a separate readiness report. Use for ambiguous story-level product behavior or when supplied discussion and artifacts must be consolidated without interviewing; not for PRDs, test strategy, repository scouting, implementation planning, or coding.

Story Clarifier

Turn rough product intent into a compact story artifact whose behavior and boundaries are explicit enough for repository scouting and implementation planning.

Modes

• Draft: create an artifact from rough intent; infer only low-risk details and label them as assumptions.
• Synthesize: consolidate supplied conversation, artifacts, and material comments without interviewing. Return a non-ready artifact when the sources are insufficient or materially conflict; do not invent a resolution.
• Rewrite: replace the source while preserving its scope, meaning, and supplied constraints; call out intentional semantic changes.
• Tighten: remove repetition and sharpen oracles without adding behavior.
• Audit: report findings against source sections or criterion IDs; do not rewrite unless asked.
• Split: create ordered, independently useful vertical slices; materialize each near-term slice with the complete Story Card contract.

Workflow

1. Select the mode. Read the full authorized referenced source and the material comments, replies, and revisions needed to interpret it before asking the user to repeat information. Preserve supplied paths, issue URLs, external identifiers, and version or revision labels exactly.
2. Map the story breadth-first before drilling into one branch: extract the actor, beneficiary, or operating situation; trigger or need; outcome and value; behavior and visible state; permissions; success, failure, and edge branches; constraints; dependencies; assumptions; non-goals; and unknowns.
3. Preserve supplied technical, policy, compliance, and interface constraints. Separate them from inferred implementation suggestions and never silently weaken or replace them. Never turn a material unverified claim into an assumption.
4. Resolve contradictions and replace vague language with observable behavior. Label only safe, reversible inferences as assumptions. Classify every material unknown using the format below.
5. For modes other than Synthesize, build the question frontier from sharp decisions whose prerequisites are settled. Ask at most three independent frontier questions per batch, do not ask a downstream question alongside its unresolved prerequisite, and recompute the frontier after each answer. In Synthesize, do not interview; if a frontier remains, preserve it and return the truthful non-ready status.
6. Choose the artifact shape, apply its contract, and run the ready check. Keep unresolved material visible.

Format every non-empty Open Questions item as one of:

• [Fact] unknown - Owner, Prerequisite, and Next action. Inspect an authorized supplied source first; route repository facts to story-repo-scout rather than asking the user to speculate. Ask the user only when they are the authoritative source or control the required access.
• [Decision] sharp choice - Owner, Prerequisite, Next action, and an evidence-backed Recommendation or None. A recommendation is not an accepted answer unless the decision owner explicitly delegates it.
• [Not yet specifiable] in-scope area - Owner, unresolved Prerequisite, and Next action that could make the question sharp. Do not fabricate a question or pre-slice this area.

Artifact State Contract

Begin every produced or revised pipeline story artifact with:

Artifact Type: Story Card | Split Story Set
Status: Ready | Needs Input | Blocked
Reason: None | <concise readiness reason>

Artifact Type describes shape, not readiness; a split set can be Ready.

• Ready: clear enough for scouting and planning, with no critical product or non-functional decision unresolved.
• Needs Input: a named answer, evidence action, or prerequisite resolution can make the artifact ready; put the smallest blocking items in Open Questions.
• Blocked: a required authority, source, or decision is unavailable, so a truthful artifact cannot yet be produced.

Always state Reason and every required contract field. Write None rather than omitting an empty field or section.

Source is required on Story Cards and Split Story Sets. Use inline or conversation when that is the actual source; otherwise preserve each supplied path, issue URL, external identifier, and version or revision. List multiple sources without replacing their identifiers with a summary. Use None only when no source is available, and never invent provenance. Use inherited from parent Split Story Set only on a Story Card while it remains nested in that set. The outer set and an audit identify their concrete source directly; when a slice is materialized as a standalone card, replace the inheritance marker with the parent's exact source list.

Story Card Contract

Use this complete schema for a single card and every materialized slice:

Artifact Type: Story Card
Status: Ready | Needs Input | Blocked
Reason: None | <concise readiness reason>
Source: <inline | conversation | path | issue URL | external identifier and revision | inherited from parent Split Story Set | None>

## Title
<Short, action-oriented title>

## Intent
Format: User Story | Job Story | Task Brief
<As a ... / When ... / direct brief naming an actor or operating situation,
trigger or need, and desired outcome>

## Feature Definition
<Concrete behavior, trigger or need, any relevant state change, and visible
>


 AC-1: 
 AC-2: 


 None


 None


 Dependencies: None
 Assumptions: None


 None


 AC-1: 

Use a user story only for a genuine user or stakeholder capability, a job story for situation-driven behavior, and a task brief for system-to-system, maintenance, or enabling work. Never invent a persona such as “the system,” “the database,” or a developer who does not receive the capability. A task brief does not need literal user-story syntax, but it must name either a real actor or beneficiary or an operating situation, plus the trigger or need and desired outcome.

Keep criterion IDs stable when meaning is unchanged and assign new IDs to new behavior. In a split set, use slice-prefixed IDs such as S1-AC-1. Put required edge, invalid, empty, permission, unavailable, timeout, and retry behavior in Acceptance Criteria. Validation Notes must cite the criteria they probe and cannot substitute for required behavior.

Split Story Set Contract

Artifact Type: Split Story Set
Status: Ready | Needs Input | Blocked
Reason: None | <concise readiness reason>
Source: <inline | conversation | path | issue URL | external identifier and revision | None>

## Shared Context
- Constraints: None
- Dependencies: None
- Assumptions: None
- Out of Scope: None
- Open Questions: None

## Slice Order
1. S1 - <first shippable outcome and why it comes first>

## Slice Dependencies
- S1:
  - Blocking slices: None
  - External prerequisites: None

## Story Slices
### S1 - <title>
<Complete Story Card contract with S1-prefixed criterion IDs>

## Deferred Work
- None

Do not replace materialized slices with abbreviated bullets. Give every materialized slice exactly one Slice Dependencies entry with separate Blocking slices and External prerequisites. Reference only declared slice IDs, reject cycles and unknown IDs, and keep Slice Order topological. This section declares gates; it does not claim they are currently satisfied. The orchestrator owns current satisfaction evidence and derives the executable frontier when selecting a slice. A split set cannot be Ready with an invalid or incomplete dependency graph.

Derive the set status from shared context and its slices: Ready requires every materialized slice to be ready; otherwise use the most severe applicable status. When nesting a complete Story Card beneath a slice heading, shift its internal Markdown heading levels as needed so they remain children of that slice while preserving every heading label, field, and section order.

Split first by a demoable, independently verifiable vertical workflow or state outcome, then by business rule, permission, data variation, or external dependency. Each slice must remain demonstrable and verifiable once its listed dependencies are satisfied. Use a discovery task brief when an unknown must be resolved before delivery. Do not split by frontend, backend, database, or setup layer unless that technical slice is itself the smallest honest deliverable.

Keep boundary categories distinct: Deferred Work is defined in-scope behavior deliberately postponed beyond the materialized slices; Out of Scope is excluded from this effort and never enters the dependency graph; [Not yet specifiable] is in scope but cannot become a slice or deferred commitment until its prerequisite makes the question sharp. Record an item in only one category.

Ready and Ambiguity Rules

An artifact is Ready only when:

• the chosen intent names a real actor or beneficiary or an operating situation, plus an explicit trigger or need and desired outcome;
• required behavior, any relevant state change, and the observable result are explicit;
• criteria give observable pass/fail oracles for required success and failure behavior;
• all contract fields are present, supplied constraints are preserved, and no hidden or critical unknown remains; and
• every material claim is supplied or verified, every material decision is accepted by its owner or explicitly delegated, and no material [Not yet specifiable] area remains.

Replace terms such as “fast,” “simple,” “secure,” “easy,” “correct,” and “handles errors” with a measurable oracle or an open question. Unknown critical performance, security, privacy, accessibility, compliance, availability, or data-loss requirements prevent Ready; never demote them to assumptions. An unanswered sharp question stays [Decision] even when its owner is currently unavailable; an area stays [Not yet specifiable] only while an unresolved prerequisite prevents a precise question. Neither is Out of Scope, and either prevents Ready when material. A material [Fact] remains non-ready until its claim is verified from an authorized source or supplied by its authoritative owner. Keep criteria independent of UI, API, storage, or architecture unless that surface is required. Flag contradictions and split multiple independent workflows, personas, triggers, or outcome branches that lack one coherent outcome.

Audit Output

For Audit, emit an audit report without presenting the findings as a replacement Story Card or Split Story Set:

Artifact Type: Story Audit
Status: Ready | Needs Input | Blocked
Reason: None | <concise assessed-readiness reason>
Assessed Artifact Type: Story Card | Split Story Set | Unstructured Story Input
Source: <inline | conversation | path | issue URL | external identifier and revision | None>

## Audit Findings
- <severity> | <section or AC ID> | <problem> | <smallest corrective action>

## Questions
- None

Status and Reason assess the source's readiness using the common family meanings; they do not describe whether the audit report was successfully written. Use Unstructured Story Input when the source does not conform to a pipeline artifact shape, and identify the assessed source without inventing provenance. Check ambiguity, contradiction, testability, failure behavior, scope coupling, and lost constraints. Do not emit a replacement artifact unless the request also asks for rewrite, tighten, or split.

Composition Boundaries

• story-clarifier owns Story Card and Split Story Set semantics; its output is consumed by story-repo-scout.
• Do not discover or invent repository paths, symbols, or architecture. Preserve supplied repository-specific constraints for the scout.
• Use story-to-plan-orchestrator when work spans clarification, repository scouting, implementation planning, packet resumption, or packet validation.
• Use documentation skills for PRDs and long specifications, tester-mindset for test strategy, story-repo-scout for repository evidence, and story-implementation-planner for plans. Do not implement code with this skill.