workflow-idea-to-pbi

Quick Summary

Goal: [Workflow] Trigger Idea to PBI workflow in one of two modes. SINGLE-PBI DEEP — capture or review idea/artifact, refine, author the §1-7 Feature Spec draft, generate TDD test specs from the idea, model the domain, plan, derive the PBI and stories, challenge review, DoR gate, mockup, prioritize (idea → draft Feature Spec → specs → from those specs to PBI). MULTI-OPPORTUNITY DISCOVERY — a raw product vision/problem → brainstorm (optionally web-research → deep-research) → RICE opportunity map → user multi-select → a light per-opportunity PBI loop → cross-PBI ranked backlog.

Mode Detection Gate (FIRST — pick the track before any step, then declare it):

Input	Mode	Track
ONE concrete idea / ticket / brief	Single-PBI Deep	full track incl. spec [mode=draft] + spec [mode=tests] + plan/plan-review/plan-validate → 1 deeply-groomed PBI. SKIP brainstorm/web-research/deep-research.
Raw product vision / problem spanning multiple opportunities	Multi-Opportunity Discovery	brainstorm (optionally web-research → deep-research) → RICE map → multi-select → light per-opportunity loop → cross-PBI prioritize. spec [mode=draft] + spec [mode=tests] + plan cycle are deep-mode only — never per opportunity; domain-analysis runs once up front.

When the input is ambiguous, ask via AskUserQuestion before step 1.

Workflow:

1. Detect — classify request scope and target artifacts.
2. Execute — apply required steps with evidence-backed actions.
3. Verify — confirm constraints, output quality, and completion evidence.

Key Rules:

• MUST ATTENTION keep claims evidence-based (file:line) with confidence >80% to act.
• MUST ATTENTION keep task tracking updated as each step starts/completes.
• MUST ATTENTION define success criteria before execution and loop until observable verification passes.
• MUST ATTENTION when creating/reviewing specs or tests, name Business Intent / Invariant Guarded or the protected business intent/invariant and ensure the test would fail if that intent breaks.
• MUST ATTENTION apply the shared SDD Artifact Contract from shared/sdd-artifact-contract.md in the active skills root; use docs/project-config.json and docs/project-reference/docs-index-reference.md for project-specific conventions.
• [BLOCKING] Tech-agnostic output: idea / PBI / story / problem-statement prose stays tech-agnostic per docs/project-reference/spec-principles.md §3 — no framework/product/language/design-pattern names; source paths and class names appear ONLY in evidence fields (**Evidence**, [Source:]), frontmatter, and Mermaid.
• MUST ATTENTION treat AI-generated ideas, PBIs, stories, mockups, and TCs as draft/reference until their review or acceptance gate approves them.
• MUST ATTENTION allow any supported AI tool to produce or review artifacts when the shared contract, synced context, and local docs are available.
• NEVER skip mandatory workflow or skill gates.

When to Use

Single-PBI Deep mode:

• PO or BA has a raw idea and needs to shape it into a grooming-ready PBI
• PO is handing off an existing ticket, PRD, or brief to the BA team for refinement
• Single-PBI refinement with stories, test specifications, challenge review, and DoR validation
• Feature needs a structured PBI before entering a sprint

Multi-Opportunity Discovery mode:

• PO/BA has a raw product vision or problem statement that spans several opportunities, and needs a prioritized backlog of multiple PBIs out of it in one pass
• A discovery sprint is needed: structured brainstorm → RICE opportunity map → multi-select → N PBIs → cross-PBI ranking (no implementation)

When NOT to Use

• Just want a (provisional) Feature Spec from an idea, no backlog → use workflow-idea-to-spec
• Already have canonical Feature Specs and only need the backlog → use workflow-spec-to-pbi (spec-first entry)
• Implementation-only (PBI already exists and is DoR-ready) → use workflow-feature or workflow-big-feature
• Bug fixes → use workflow-bugfix

Key Mechanics

1. Step Selection Gate

After confirming the workflow, present the full step list and let the user deselect irrelevant steps:

- [x] Brainstorm (brainstorm)                      — DISCOVERY MODE ONLY; RICE opportunity map
- [ ] Market research (web-research)               — DISCOVERY MODE, CONDITIONAL
- [ ] Deep research (deep-research)                 — DISCOVERY MODE, CONDITIONAL; runs only when web-research ran
- [x] Idea capture (idea)                          — REPEATS per opportunity in discovery mode
- [x] Spec & code discovery (spec-discovery)       — investigate related/affected specs + code before authoring
- [ ] Review existing artifact (artifact-review)   — CONDITIONAL
- [ ] PO → BA handoff (handoff)                    — CONDITIONAL
- [x] Refine to PBI (refine)                        — REPEATS per opportunity in discovery mode
- [x] Refinement rationale review (why-review)
- [x] Feature Spec draft (spec [mode=draft])        — DEEP MODE ONLY; §1-7 Feature Spec (provisional) before §8 tests
- [x] Test specifications (spec [mode=tests])       — DEEP MODE ONLY; idea → draft → specs
- [x] Test-spec rationale review (why-review)       — deep mode
- [x] Test specification review (artifact-review --type=spec-tests)  — deep mode
- [ ] Domain analysis (domain-analysis)            — CONDITIONAL; discovery mode runs it ONCE up front
- [x] Domain rationale review (why-review)
- [x] Implementation plan (plan)                    — DEEP MODE ONLY
- [x] Plan review (plan-review)                     — deep mode
- [x] Plan validation (plan-validate)               — deep mode
- [x] Plan rationale review (why-review)            — deep mode
- [x] PBI review (artifact-review --type=pbi)       — from specs to PBI; REPEATS per opportunity
- [x] User stories (story)                          — REPEATS per opportunity
- [x] Story rationale review (why-review)
- [x] Story review (artifact-review --type=story)   — REPEATS per opportunity
- [x] Dev BA PIC challenge (pbi-challenge)          — REPEATS per opportunity
- [x] Definition of Ready gate (dor-gate)           — REPEATS per opportunity
- [x] PBI HTML mock-up (pbi-mockup)                — CONDITIONAL; REPEATS per opportunity; faithfully matches current UI system
- [x] UI design spec (design-spec)                  — CONDITIONAL (UI PBIs); REPEATS per opportunity; UI specs after the mockup
- [x] Backlog prioritization (prioritize)           — cross-PBI in discovery mode
- [x] Documentation synchronization (docs-update)

Mark skipped steps as completed immediately. In single-PBI deep mode, deselect brainstorm/web-research/deep-research. In discovery mode, deselect spec [mode=draft], spec [mode=tests], artifact-review --type=spec-tests, and the plan/plan-review/plan-validate cycle (deep-mode-only); run domain-analysis once up front.

1a. Multi-Opportunity Discovery Loop (Discovery Mode core mechanic)

Activated only when the input is a raw product vision/problem spanning multiple opportunities (folded in from the former product-discovery workflow).

1. Brainstorm → opportunity map. Run /brainstorm with Double Diamond (problem framing → opportunity framing → ideation → convergence). Output a RICE-scored opportunity map of 3–8 items to plans/{plan-dir}/brainstorm-opportunity-map.md.
2. Multi-select. Present the map via AskUserQuestion (multiSelect: true): "Which opportunities should we develop into PBIs?"
3. Opportunity-map why-review gate (before the loop): challenge whether the top-ranked opportunities are the right problems, whether RICE Reach/Impact are founded or speculative, run a pre-mortem, and name systemic alternatives. FAIL on a high-ranked opportunity → drop it or revisit framing; WARN → document and proceed with user acknowledgment.
4. Task decomposition gate. Call TaskCreate for EVERY task (N opportunities × 9 loop steps = N×9 minimum) BEFORE processing any opportunity — never start the loop without a complete task list.
5. Per-opportunity light loop (for EACH selected opportunity — NO spec [mode=draft], NO spec [mode=tests], NO plan/plan-review/plan-validate; domain-analysis already ran once up front): /idea → /refine → /artifact-review --type=pbi → /story → /artifact-review --type=story → /pbi-challenge → /dor-gate → /pbi-mockup → /design-spec (mockup + UI specs skip for backend-only PBIs).
6. Scale management. For 6+ selected opportunities, spawn one sub-agent per opportunity (each gets brainstorm context + its task list); the main context runs /prioritize at the end. Update a session summary table after every 3 opportunities.
7. Cross-PBI prioritize. After ALL opportunities are processed, run /prioritize across all session PBIs (cross-PBI RICE + dependency graph) → sprint-ready ranked backlog, flagging Must/Should/Could-Have. /prioritize MUST write the resulting rank/priority back into EACH PBI's frontmatter (priority propagation), not only the standalone backlog — so /pbi-mockup (header badge) and /feature-presentation (Scope & backlog slide) can surface each PBI's priority from the PBI itself.

Spec-hub coupling (§6 interaction surface ↔ UI artifacts): for UI PBIs the /pbi-mockup and /design-spec produced here are NOT standalone artifacts — they are the deep companions of the governing Feature Spec's §6 interaction surface (View Inventory / Navigation Map / Key UI States / per-story click-path). The §6 thin intent seeds both; design-spec records its path in the spec's design_spec: frontmatter (and the mockup in mockup:) so the spec stays the navigable hub: a reader goes spec → §6 thin intent → mockup + design-spec deep companions, and the three never drift. Keep deep visual fidelity (layout, tokens, pixel detail) in the mockup/design-spec, never in §6. See the SYNC:ui-intent-layer block below for the full rule — do not restate it here. Backend-only PBIs (no UI) → skip /pbi-mockup + /design-spec and state that reason.

2. TaskCreate Before Starting

MANDATORY IMPORTANT MUST ATTENTION — Call TaskCreate for every step before beginning any work:

TaskCreate: "Brainstorm → RICE opportunity map" [discovery mode]
TaskCreate: "Market research (web-research)" [discovery mode, conditional]
TaskCreate: "Deep research (deep-research)" [discovery mode, conditional; only when web-research ran]
TaskCreate: "Idea capture"
TaskCreate: "Refine to PBI"
TaskCreate: "Refinement rationale review (why-review after refine)"
TaskCreate: "Feature Spec draft (spec [mode=draft])"
TaskCreate: "Test specifications (spec [mode=tests])"
TaskCreate: "Test-spec rationale review (why-review after spec [mode=tests])"
TaskCreate: "Test specification review (artifact-review --type=spec-tests)"
TaskCreate: "Domain analysis (domain-analysis)" [if domain entities change]
TaskCreate: "Domain rationale review (why-review after domain-analysis)"
TaskCreate: "Implementation plan (plan)"
TaskCreate: "Plan review (plan-review)"
TaskCreate: "Plan validation (plan-validate)"
TaskCreate: "Plan rationale review (why-review after plan-validate)"
TaskCreate: "PBI review (artifact-review --type=pbi)"
TaskCreate: "User stories (story)"
TaskCreate: "Story rationale review (why-review after story)"
TaskCreate: "Story review"
TaskCreate: "Dev BA PIC challenge"
TaskCreate: "Definition of Ready gate"
TaskCreate: "PBI HTML mock-up" [if UI]
TaskCreate: "Prioritize"
TaskCreate: "Documentation synchronization (docs-update)"
TaskCreate: "Session summary (watzup)"

One task per step. Mark each completed immediately when done — never batch.

3. Why-Review Gates (Purpose-Specific, Repeated)

This is the adversarial design rationale check. Purpose: validate the WHY of each artifact before investing in the next.

The workflow contains repeated /why-review gates after the non-review artifact steps. Use purpose-specific labels in sequence: refinement rationale (after refine), test-spec rationale (after spec [mode=tests]), domain rationale (after domain-analysis), plan rationale (after plan-validate), and story rationale (after story). Do not deduplicate them.

The standalone gate after artifact-review --type=pbi is intentionally omitted: artifact-review --type=pbi (like every review skill) already self-invokes /why-review --validate-findings as an internal Findings Validation Gate, so a separate why-review step right after it would be duplicate work.

Challenge prompts:

• Is this the right solution to the stated problem? What was rejected and why?
• Are the acceptance criteria constraints justified? What happens if any constraint is removed?
• Pre-mortem: if this PBI ships and fails in 3 months, what breaks?
• Are there simpler alternatives not yet considered?
• Does the scope align with the stated business value?

Output: Why-Review checklist with PASS / WARN / FAIL.

Result	Action
PASS	Proceed to the next artifact step
WARN	Document risk, proceed with user acknowledgment
FAIL	Revise PBI in /refine before continuing

4. TDD-Spec Gate (After refine + spec [mode=draft], Before the PBI is drafted)

Author the canonical §1-7 Feature Spec with /spec [mode=draft] (idea-sourced, provisional, §8 Evidence: TBD), then generate and review §8 test specifications right after refine — BEFORE the PBI is drafted — so the PBI, stories, and plan are derived FROM the draft Feature Spec + its test specs (idea → draft Feature Spec → specs → from those specs to PBI).

AI-generated TC drafts are reference-only until /artifact-review --type=spec-tests, /pbi-challenge, and /dor-gate accept them for delivery planning.

Output requirements:

• Map material acceptance criteria and user stories to TC IDs
• Route planned TC IDs to Feature doc Section 8 through /spec [mode=tests]; /docs-update later verifies feature docs and §8 TC ↔ executing test code sync.
• Cover happy path, validation failure, authorization/permission, and important edge cases where applicable
• Run /artifact-review --type=spec-tests before /pbi-challenge

5. PBI Output Format

Each PBI artifact must contain:

Section	Content
Title	Clear, actionable
Problem Statement	Why this needs to exist
Hypothesis	If we build X, users will Y, which drives Z
Acceptance Criteria	GIVEN / WHEN / THEN format
RICE Score	Reach × Impact × Confidence / Effort
User Stories	Who / What / Why
Test Specs	TC IDs mapped to acceptance criteria
DoR Status	PASS / WARN / FAIL
Mockup	HTML mock-up based on project reference design docs (if UI)

6. Artifact Locations

Step	Output Path
Idea	team-artifacts/ideas/{YYMMDD}-{role}-idea-{slug}.md
PBI	team-artifacts/pbis/{YYMMDD}-pbi-{slug}.md
Stories	Added to PBI artifact
Test specs	Feature doc Section 8 (canonical TC registry)
DoR result	Added to PBI artifact
Mockup	HTML mock-up file saved beside PBI artifact
Prioritization	team-artifacts/backlog/{YYMMDD}-backlog-update.md
Docs sync	plans/reports/docs-update-{YYMMDD}-{HHMM}.md

These roots intentionally match the child skills (idea, refine, story, pbi-mockup, prioritize, docs-update). If artifact roots become configurable later, update this workflow and all child skills in the same change.

Write output IMMEDIATELY after each step — never batch across steps.

7. Conditional Skip Rules

Step	Skip When
/brainstorm	Single-PBI deep mode (one concrete idea/ticket)
/web-research	Single-PBI deep mode, internal tool, or well-understood domain
/deep-research	Single-PBI deep mode, or whenever web-research is skipped (runs only when it ran)
/artifact-review	No existing artifact — raw idea input
/spec [mode=draft]	Discovery mode (deep-mode only — never per opportunity)
/spec [mode=tests], /artifact-review --type=spec-tests	Discovery mode (deep-mode only — never per opportunity)
/domain-analysis	Idea introduces no new/changed domain entities; in discovery mode run ONCE up front
/plan, /plan-review, /plan-validate	Discovery mode (deep-mode only — never per opportunity)
/pbi-mockup	Backend-only PBI — no UI changes

---

8. Near-Final Documentation Synchronization

Run /docs-update after /prioritize and before /workflow-end.

Purpose:

• Sync refined PBI/story outputs into business feature docs where applicable.
• Sync feature doc Section 8 test specifications and docs/specs/ dashboards after /artifact-review --type=spec-tests.
• Verify specs, feature docs, and TDD/spec docs do not drift before workflow closure.
• Record skipped sub-phases explicitly when no impacted docs exist.

---

IMPORTANT MANDATORY Steps: /web-research -> /deep-research -> /brainstorm -> /idea -> /spec-discovery -> /artifact-review -> /refine -> /why-review -> /spec [mode=draft] -> /spec [mode=tests] -> /why-review -> /artifact-review --type=spec-tests -> /spec-clarify -> /domain-analysis -> /why-review -> /plan -> /plan-review -> /plan-validate -> /why-review -> /artifact-review --type=pbi -> /story -> /why-review -> /artifact-review --type=story -> /pbi-challenge -> /dor-gate -> /pbi-mockup -> /design-spec -> /prioritize -> /docs-update -> /feature-presentation -> /workflow-end -> /watzup

Mode gating of the canonical sequence above — Single-PBI deep mode: skip /brainstorm + /web-research + /deep-research; run the full deep track (one PBI). Discovery mode: run /brainstorm (optionally /web-research → /deep-research), skip /spec [mode=draft], /spec [mode=tests], /artifact-review --type=spec-tests, /spec-clarify, /plan, /plan-review, /plan-validate; loop /idea→/refine→/artifact-review --type=pbi→/story→/artifact-review --type=story→/pbi-challenge→/dor-gate→/pbi-mockup→/design-spec per selected opportunity, then /prioritize cross-PBI.

[BLOCKING] Each step MUST ATTENTION invoke its Skill tool — marking a task completed without skill invocation is a workflow violation. NEVER batch-complete validation gates.

Activate the workflow-idea-to-pbi workflow. Run /start-workflow workflow-idea-to-pbi with the user's prompt as context.

Steps: /web-research → /deep-research → /brainstorm → /idea → /spec-discovery → /artifact-review → /refine → /why-review → /spec [mode=draft] → /spec [mode=tests] → /why-review → /artifact-review --type=spec-tests → /spec-clarify → /domain-analysis → /why-review → /plan → /plan-review → /plan-validate → /why-review → /artifact-review --type=pbi → /story → /why-review → /artifact-review --type=story → /pbi-challenge → /dor-gate → /pbi-mockup → /design-spec → /prioritize → /docs-update → /feature-presentation → /workflow-end → /watzup

Conditional / mode-gated steps:

• /brainstorm, /web-research, /deep-research — DISCOVERY MODE only; skip in single-PBI deep mode (/deep-research runs only when /web-research ran)
• /spec [mode=draft], /spec [mode=tests], /artifact-review --type=spec-tests, /plan, /plan-review, /plan-validate — DEEP MODE only; never run per opportunity in discovery mode
• /artifact-review — skip if no existing artifact/ticket/PRD; proceed straight to /refine
• /domain-analysis — skip if the idea introduces no new/changed domain entities; in discovery mode run once up front
• /pbi-mockup — skip if PBI is backend-only (no UI changes); when run, the mockup MUST faithfully match the current UI system (gated by SYNC:existing-ui-research)
• /design-spec — UI PBIs only (runs right after /pbi-mockup); skip if PBI is backend-only; authors the PBI's tech-agnostic UI specs, gated by SYNC:existing-ui-research

---

<!-- SYNC:ai-mistake-prevention -->

AI Mistake Prevention — Failure modes to avoid on every task:

Re-read files after context changes. Context compaction, resume, or long-running work can make memory stale; verify current files before acting. Verify generated content against source evidence. AI hallucinates APIs, names, claims, and document facts. Check the relevant source before documenting or referencing. Check downstream references before deleting or renaming. Removing an artifact can stale docs, generated mirrors, configs, and callers; map references first. Trace the full impact chain after edits. Changing a definition can miss derived outputs and consumers. Follow the affected chain before declaring done. Verify ALL affected outputs, not just the first. One green check is not all green checks; validate every output surface the change can affect. Assume existing values are intentional — ask WHY before changing OR flagging one as a defect. Before changing or reporting a constant, limit, flag, cutoff, wording, or pattern, read nearby context and history, the CALLER's ordering, and 2+ sibling call sites of the same convention. A doc stating WHAT without WHY is missing rationale, not proof of a missing guard. Surface ambiguity before acting — don't pick silently. Multiple valid interpretations require an explicit question or stated assumption with risk. Assert the outcome your system owns, not the intermediate state your infrastructure owns. When verifying async work, assert the final business state — never the delivery/retry bookkeeping held in shared infrastructure that any co-running process can write. Such a check passes when run alone and flakes the moment anything else shares that infrastructure. Keep shared guidance role-relevant. Universal guidance must help every receiving skill or agent; code-specific obligations belong only in code-specific protocols.

<!-- /SYNC:ai-mistake-prevention --> <!-- SYNC:nested-task-creation -->

Nested Task Expansion Contract — For workflow-step invocation, the [Workflow] ... row is only a parent container; the child skill still creates visible phase tasks.

1. Call TaskList first. If a matching active parent workflow row exists, set nested=true and record parentTaskId; otherwise run standalone.
2. Create one task per declared phase before phase work. When nested, prefix subjects [N.M] $skill-name — phase.
3. When nested, link the parent with TaskUpdate(parentTaskId, addBlockedBy: [childIds]).
4. Orchestrators must pre-expand a child skill's phase list and link the workflow row before invoking that child skill or sub-agent.
5. Mark exactly one child in_progress before work and completed immediately after evidence is written.
6. Complete the parent only after all child tasks are completed or explicitly cancelled with reason.

Blocked until: TaskList done, child phases created, parent linked when nested, first child marked in_progress.

<!-- /SYNC:nested-task-creation --> <!-- SYNC:critical-thinking-mindset -->

Critical Thinking Mindset — Apply critical thinking, sequential thinking. Every claim needs traced proof, confidence >80% to act. Anti-hallucination: Never present guess as fact — cite sources for every claim, admit uncertainty freely, self-check output for errors, cross-reference independently, stay skeptical of own confidence — certainty without evidence root of all hallucination.

<!-- /SYNC:critical-thinking-mindset --> <!-- SYNC:incremental-persistence -->

Incremental Result Persistence — MANDATORY for all sub-agents or heavy inline steps processing >3 files.

1. Before starting: Create report file plans/reports/{skill}-{date}-{slug}.md
2. After each file/section reviewed: Append findings to report immediately — never hold in memory
3. Return to main agent: Summary only (per SYNC:subagent-return-contract) with Full report: path
4. Main agent: Reads report file only when resolving specific blockers

Why: Context cutoff mid-execution loses ALL in-memory findings. Each disk write survives compaction. Partial results are better than no results.

Report naming: plans/reports/{skill-name}-{YYMMDD}-{HHmm}-{slug}.md

<!-- /SYNC:incremental-persistence --> <!-- SYNC:subagent-return-contract -->

Sub-Agent Return Contract — When this skill spawns a sub-agent, the sub-agent MUST return ONLY this structure. Main agent reads only this summary — NEVER requests full sub-agent output inline.

## Sub-Agent Result: [skill-name]

Status: ✅ PASS | ⚠️ PARTIAL | ❌ FAIL
Confidence: [0-100]%

### Findings (Critical/High only — max 10 bullets)

- [severity] [file:line] [finding]

### Actions Taken

- [file changed] [what changed]

### Blockers (if any)

- [blocker description]

Full report: plans/reports/[skill-name]-[date]-[slug].md

Main agent reads Full report file ONLY when: (a) resolving a specific blocker, or (b) building a fix plan. Sub-agent writes full report incrementally (per SYNC:incremental-persistence) — not held in memory.

Context budget — the return payload is a SUMMARY, not a transcript: ≤10 finding bullets, no raw file contents / full diffs / verbatim logs inline, no re-pasted source. Everything beyond the summary lives in the Full report on disk. A sub-agent that would exceed the summary shape MUST write the detail to its report and return only the pointer — the orchestrator's context is the scarce resource the whole map-reduce protects.

<!-- /SYNC:subagent-return-contract --> <!-- SYNC:ui-intent-layer -->

[BLOCKING] Capture a tech-agnostic UI/UX intent layer in every UI-bearing spec — a reader must be able to visualize how the feature works without naming any technology. When the feature has a user interface, the spec MUST ATTENTION carry an interaction-surface section so the application — not just its API — can be rebuilt on any stack:

1. View Inventory — list each view/screen by its UX ROLE and purpose (e.g. "list of items", "item editor", "confirmation step") and what information it presents. Describe by role, never by an implementation name.
2. Navigation Map — how a user moves between views: entry points, transitions, and exits. Trace how this surface connects to neighboring features already in the system.
3. Key observable UI States — the distinct states a user can observe per view (empty, loading, populated, error, success, permission-denied, etc.) — described as what the user perceives, not how it is rendered.
4. Per-story interaction flow — for each user story, the step-by-step click/action path from intent to outcome, cross-referenced to the logical IDs the spec already owns (US-/OP-/BR-).
5. Couple to the companion design artifact — keep deep visual fidelity (layout, tokens, pixel detail) OUT of the spec; it lives in the linked design-spec/mockup. Record that companion's path in the spec frontmatter so the spec stays the navigable hub.

M1-clean (NON-NEGOTIABLE): the prose names ZERO frameworks, routes/URLs, CSS, or component-class names — only roles, information, states, and flows. Technology detail belongs in the companion design artifact, never here.

Skip ONLY when the feature is backend-only (no UI) — state that reason explicitly in the section.

<!-- /SYNC:ui-intent-layer --> <!-- SYNC:critical-thinking-mindset:reminder -->

MUST ATTENTION apply critical + sequential thinking — every claim needs appropriate traced evidence (file:line for repo/code claims; source URL or artifact section for research, product, content, and docs claims); confidence >80% to act, <60% DO NOT recommend. Anti-hallucination: never present guess as fact, admit uncertainty freely, cross-reference independently, stay skeptical of own confidence.

<!-- /SYNC:critical-thinking-mindset:reminder --> <!-- SYNC:ai-mistake-prevention:reminder -->

MUST ATTENTION apply AI mistake prevention — verify generated content against evidence, trace downstream references before deleting or renaming, verify all affected outputs, re-read files after context loss, and surface ambiguity before acting.

<!-- /SYNC:ai-mistake-prevention:reminder --> <!-- SYNC:nested-task-creation:reminder -->

• MANDATORY Parent workflow rows do not replace child phase tracking; expand phases and link the parent when nested.
• MANDATORY Orchestrators pre-expand child skill phases before invocation; use [N.M] $skill-name — phase prefixes and one-in_progress discipline.

<!-- /SYNC:nested-task-creation:reminder --> <!-- SYNC:ui-intent-layer:reminder -->

• MANDATORY For UI-bearing specs, author/maintain the tech-agnostic interaction-surface layer (View Inventory + Navigation Map + observable UI States + per-story US-/OP-/BR--traced flow); keep deep visual fidelity in the linked design-spec/mockup recorded in frontmatter; name ZERO frameworks/routes/CSS/component classes; skip ONLY for backend-only features with a stated reason.

<!-- /SYNC:ui-intent-layer:reminder --> <!-- SYNC:parallel-subagent-dispatch -->

Parallel Sub-Agent Dispatch — Plan parallelism the moment a task breakdown exists, BEFORE executing it — running provably independent tasks sequentially wastes wall-clock. Applies to every multi-step job: workflow steps, planning, batch updates, investigation, research, scans, reviews, doc sync. Plan execution is metadata-gated, NEVER default-parallel — fan-out follows ONLY what the plan declares (PAR/SEQ tags + per-phase write set); an untagged plan runs sequentially — why: a derived write set cannot see cascade or generated writes.

1. Tag every task PAR or SEQ. PAR = inputs exclude every pending task's output AND write set disjoint from every other PAR. Else SEQ — MUST ATTENTION name the dependency forcing it.
2. Group PAR into waves. No edge between members. Two writers of one file NEVER share a wave. Read-only work (search, investigation, review, research) parallelizes freely.
3. Declare before dispatch: Parallel plan: wave 1 = [...] · wave 2 = [...] · SEQ = [...] (reason).
4. Spawn each wave in ONE message — every Agent call in one response, NEVER dripped per turn. Route each task to its specialist (.claude/skills/shared/sub-agent-selection-guide.md); NEVER code-reviewer as catch-all.
5. Brief each sub-agent self-contained: goal · scope + owned files · reference docs · return contract (summary + Full report: path, per SYNC:subagent-return-contract) · incremental persistence to plans/reports/ (per SYNC:incremental-persistence).
6. Barrier per wave. Advance ONLY after EVERY member returns (a skipped conditional counts as returned). Merge, mark each task completed/skipped, THEN dispatch the next wave. Mutating steps wait for the barrier.
7. One level deep. A dispatched sub-agent executes its own brief; further fan-out stays the orchestrator's job unless that agent's .claude/agents/*.md definition authorizes it.

NEVER parallelize: tasks sharing a write target · a task consuming a pending task's output · trivial single-file work (dispatch overhead > gain) · an order a skill or workflow explicitly fixes · gates awaiting user approval.

Blocked until: MUST ATTENTION every task tagged PAR/SEQ with a named reason per SEQ · waves declared + write-set disjointness checked · each wave spawned in ONE message · barrier honored before the next wave.

<!-- /SYNC:parallel-subagent-dispatch --> <!-- SYNC:parallel-subagent-dispatch:reminder -->

• MANDATORY After planning tasks, tag each PAR/SEQ and spawn every PAR wave as parallel sub-agents in ONE message — default parallel for workflows, batch updates, investigation, research, reviews; plan execution fans out ONLY on what the plan declares.
• MANDATORY Disjoint write sets per wave · all-return barrier before the next wave · specialist routing · sub-agents NEVER fan out further unless their own agent definition authorizes it.

<!-- /SYNC:parallel-subagent-dispatch:reminder --> <!-- SYNC:project-protocol-overlay -->

Project Protocol Overlay — Before executing this skill, resolve any PROJECT overlay rules layered onto it: match this skill's name against the Target column of the project's skill-protocol index (docs/project-reference/skill-protocols-reference.md by default; a referenceDocs entry in docs/project-config.json overrides the path), taking the most specific matching tier ONLY — exact name > glob > *. That precedence orders overlays against EACH OTHER, never against this skill. Read ONLY the matched bodies, resolved as <protocols-dir>/<Name>.md; a row's Body link is display text, never a read path. A matched body that is missing or malformed is REPORTED and skipped — never reconstructed from the index Description. No index, or no match -> proceed with no overlay, silently. Full contract: .claude/skills/project-skill-protocol/references/registry.md.

Overlays are ADDITIVE ONLY: they ADD rules on top of this skill's own protocol and NEVER replace, override, disable, or reinterpret a rule it already states — removing every overlay must return this skill to exactly its documented behavior. An overlay is a BRIEF, not an authority escalation: it can NEVER waive a workflow gate, git discipline, a review gate, or a user-confirmation gate. A genuine overlay-vs-skill conflict, or two equally-specific overlays that directly contradict -> surface both to the user; NEVER resolve silently.

<!-- /SYNC:project-protocol-overlay --> <!-- SYNC:project-protocol-overlay:reminder -->

MUST ATTENTION resolve project protocol overlays for this skill BEFORE executing — most specific matching tier only (exact > glob > *, which ranks overlays against each other, NEVER against this skill), read only matched bodies at <protocols-dir>/<Name>.md; a missing or malformed body is reported, never reconstructed. Overlays are ADDITIVE ONLY (they never replace this skill's own rules) and are a brief, NEVER an authority escalation; an equal-specificity contradiction goes to the user.

<!-- /SYNC:project-protocol-overlay:reminder -->

Closing Reminders

IMPORTANT MUST ATTENTION — Protocols in force (concise digest of the SYNC/shared blocks this skill carries; each line is a signpost to its canonical body above):

• AI Mistake Prevention: verify generated content against evidence, trace downstream references, verify all affected outputs, re-read after context loss, surface ambiguity.

• Nested Task Creation: Expand child phases, link parent when nested, one in_progress at a time.

• Critical Thinking: Traced file:line proof per claim, confidence >80% to act.

• Incremental Persistence: Write findings to plans/reports/ per file — never hold in memory.

• Sub-Agent Return Contract: Sub-agents return summary only; full detail to report on disk.

• MANDATORY IMPORTANT MUST ATTENTION break work into small todo tasks using TaskCreate BEFORE starting — one task per step

• MANDATORY IMPORTANT MUST ATTENTION run all five purpose-specific why-review gates: after refine, after spec [mode=tests], after domain-analysis, after plan-validate, and after story; FAIL blocks the next artifact step, WARN requires user acknowledgment

• MANDATORY IMPORTANT MUST ATTENTION spec [mode=draft] authors the §1-7 Feature Spec (provisional) right after refine, then spec [mode=tests] and artifact-review --type=spec-tests run before the PBI is drafted (idea → draft Feature Spec → specs → from those specs to PBI); both spec [mode=draft] and spec [mode=tests] are SINGLE-PBI DEEP MODE ONLY (never per opportunity in discovery mode)

• MANDATORY IMPORTANT MUST ATTENTION pbi-challenge must be run by a reviewer different from the drafter

• MANDATORY IMPORTANT MUST ATTENTION dor-gate must pass (PASS or WARN) before pbi-mockup is finalized; for UI PBIs, pbi-mockup AND design-spec both run (mockup first, then UI specs) so the PBI carries a faithful mockup matching the current UI system PLUS UI specs — both skip for backend-only PBIs and both are gated by SYNC:existing-ui-research; the code-producing design lanes are reference-only, not part of this workflow

• MANDATORY IMPORTANT MUST ATTENTION write each artifact immediately — never batch output across steps

• MANDATORY IMPORTANT MUST ATTENTION prioritize must write the resulting rank/priority back into EACH PBI's frontmatter (priority propagation) — not only the standalone backlog — and that priority MUST then surface in the pbi-mockup generated files (header badge) and the feature-presentation deck (Scope & backlog slide, ranked order + priority label per PBI)

• MANDATORY IMPORTANT MUST ATTENTION docs-update runs after prioritize and before workflow-end to sync specs, feature docs, and TDD/spec dashboards

• MANDATORY IMPORTANT MUST ATTENTION feature-presentation runs after docs-update and before workflow-end to synthesize one standalone stakeholder HTML deck (surfacing each PBI's priority/rank)

• MANDATORY IMPORTANT MUST ATTENTION add a final watzup summary: PBI title, DoR result, any blocking items, recommended next step

• Parallel Sub-Agent Dispatch: Tag tasks PAR/SEQ, group PAR into disjoint-write-set waves, spawn each wave in ONE message, barrier before advancing.

[TASK-PLANNING] Before acting, analyze task scope and systematically break it into small todo tasks and sub-tasks using TaskCreate.

[IMPORTANT] Analyze how big the task is and break it into many small todo tasks systematically before starting — this is very important.