Skill v1.0.1
currentAutomated scan100/100+3 new
version: "1.0.1" name: clarify-spec description: "Clarify product, technical, and operational specs with targeted questions and write accepted answers into spec.md."
Business Analyst — Clarify Spec Workflow
<rules>
- Report compact progress at major milestones: outcome, key delta, next step.
- Max 8 questions per session.
- Always use batch mode: present all questions in one numbered list; apply updates atomically.
- Each question: multiple-choice (2-5 options) or short answer (≤5 words), with recommended answer + rationale. Select-style prompts with free-text allowed.
- Write answers into
spec.mdatomically after all answers are collected. - Never create
spec.md— if missing, direct to/sddp-specify. - Runs before
/sddp-plan; warn when skipping increases rework risk. - Reuse
FEATURE_DIR/research.md; refresh only unresolved or materially changed areas. - Delegate external research only to Technical Researcher.
</rules>
<workflow>
0. Acquire Shared Skills
Use full prose when compression could weaken question meaning.
1. Resolve Context
Delegate: Context Gatherer in quick mode → resolve FEATURE_DIR.
- Require
HAS_SPEC = true. If false → ERROR: "Missing spec.md atFEATURE_DIR/spec.md. Run/sddp-specify." - Read
FEATURE_DIR/spec.md. Read frontmatter; treat missingspec_typeasproduct.
2. Scan for Ambiguities
Delegate: Requirements Scanner (.github/agents/_requirements-scanner.md):
- Provide
SpecPath = FEATURE_DIR/spec.md. - Use returned
coverage_statusandquestionsfor activespec_type.
3. Reuse or Refresh Research
If FEATURE_DIR/research.md exists → read, map findings to ambiguity categories, reuse covered categories, refresh only unresolved/weak/changed ones.
If critical areas still lack support:
Delegate: Technical Researcher (.github/agents/_technical-researcher.md):
- Topics: Standards/patterns for unresolved ambiguity categories only
- Context: Feature spec,
spec_type, detected ambiguities - Purpose: "Strengthen recommended answers with evidence-based reasoning."
- File Paths:
FEATURE_DIR/spec.md,FEATURE_DIR/research.mdwhen present
Use findings to strengthen recommended answers.
When persisting: rewrite full FEATURE_DIR/research.md, merge by topic, plan-authoring research format, max 2 sources/topic, ≤4KB (consolidate if >3KB).
4. Select Questions
From questions → select up to 8 highest-impact items.
5. Ask Questions
5.0 Present Questions
AUTOPILOT = true→ auto-select recommended for every question. Log each as adecisionrow toautopilot-log.md: Timestamp=now, Phase=Clarify, Event=decision, Detail="Clarification Q[N]: '[question]'", Outcome="[answer]", Rationale="recommended default", Artifacts=[spec.md](spec.md). Continue to Step 6.AUTOPILOT = false→ present all questions in a single numbered list with marked recommendations. Allow free-form answers. Validate all responses, record, and continue to Step 6.
6. Integrate Answers
Update spec.md once after all answers are collected.
Per answer:
- Ensure
## Clarificationssection exists. - Under
### Session YYYY-MM-DD, append- Q: <question> -> A: <answer>. - Apply to best section:
- Product functional/UX →
User Scenarios & TestingorRequirements - Technical →
Technical Objectives,Requirements, orIntegration Points - Operational →
Operational Objectives,Requirements, orIntegration Points - Data →
Key Entitieswhen present - Non-functional →
Success Criteriaor relevantRequirementssubsection with measurable targets - Scenario → acceptance/validation/verification criteria per
spec_type - Terminology → normalize across spec
- Replace invalidated statements; no contradictions.
- Save atomically after each integration pass.
6.5. Adversarial Stress-Test
After collaborative answers are integrated, attack the resolved spec for internal contradictions.
Delegate: Adversarial Scanner (.github/agents/_adversarial-scanner.md):
- Provide
SpecPath = FEATURE_DIR/spec.md. - Use returned
findingsarray.
If findings is empty → skip to Step 7.
6.5.1 Present Findings
AUTOPILOT = true→ auto-accept recommended resolution for every finding.
Log each as a decision row to autopilot-log.md: Timestamp=now, Phase=Clarify, Event=decision, Detail="Stress-test STF-### '[summary]'", Outcome="[resolution]", Rationale="recommended default", Artifacts=[spec.md](spec.md). Apply resolutions inline. Continue to 6.5.2.
AUTOPILOT = false→ present all findings in a single numbered list.
Each finding shows: ID, summary, category, severity, affected IDs, Given/When/Then scenario, recommended resolution. Allow user to accept, override, or defer each finding.
6.5.2 Write Findings
- Ensure
## Stress-Test Findingssection exists inspec.md(after## Clarificationsif present, else after## Success Criteria). - Under
### Session YYYY-MM-DD, add each finding inSTF-###format perartifact-conventions/SKILL.md, using the scanner-providedsummaryas the persisted summary text. - For each CRITICAL or HIGH finding the user did not resolve:
- Count existing
[NEEDS CLARIFICATION]markers in spec. - If count < 3: add
[NEEDS CLARIFICATION: STF-###]to the first affected spec entry in this priority order: requirement, success criterion, then user story/objective heading. If no affected ID maps cleanly to a concrete spec entry, append the marker to the finding entry itself. - If count >= 3: do NOT add marker. Instead append
[DEFERRED TO NEXT CLARIFY]tag to the finding entry and warn user that a follow-up/sddp-clarifypass is recommended.
- For accepted/overridden findings: apply resolution to the affected spec entries inline, same integration rules as Step 6 (replace invalidated statements, no contradictions).
- Save atomically.
7. Validate
After each write verify:
- Clarifications section has one bullet per recorded answer
- Total questions ≤ 8
- Targeted vague placeholders resolved
- No contradictory statements remain
- Terminology consistent across updated sections
- Stress-Test Findings section (if present) has one entry per recorded finding
- No CRITICAL/HIGH finding left without either an inline resolution or a
[NEEDS CLARIFICATION: STF-###]marker (unless deferred due to 3-marker cap)
7.5. Update Spec Maturity
After successful clarification (at least one answer integrated):
- Update
spec_maturityin frontmatter fromdrafttoclarified - Update the
**Spec Maturity**:header field to match
8. Report
Output:
- Questions asked/answered count
- Stress-test findings count (resolved / deferred / total)
- Path to updated spec
- Sections touched
- Coverage summary table from updated
coverage_status - Whether outstanding items justify another
/sddp-clarifypass - Next steps:
/sddp-clarify(optional — if deferred items or stress-test findings justify another pass) — suggested prompt. If deferred stress-test findings exist, suggest: "Focus on deferred stress-test findings STF-###, STF-###."/sddp-plan(required) — suggested prompt
</workflow>