# Workflow Idea To Pbi > [Workflow] Use when activating the Idea to PBI workflow for turning an idea — or a raw product vision/problem — into prioritized PBIs and stories (single-PBI deep mode, or multi-opportunity discovery mode). - Skill: `duc01226/workflow-idea-to-pbi` (Agent Skill) - Install (CLI): `npx skillmds@latest add duc01226/workflow-idea-to-pbi` - Raw SKILL.md: https://api.skillmd.com/api/skills/duc01226/workflow-idea-to-pbi/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Product & Planning - Author: duc01226 (https://skillmd.com/u/duc01226) - Updated: 2026-09-09 - Page: https://skillmd.com/skills/duc01226/workflow-idea-to-pbi --- > Codex compatibility note: > > - Invoke repository skills with `$skill-name` in Codex; this mirrored copy rewrites legacy Claude `/skill-name` references. > - Task tracker mandate: BEFORE executing any workflow or skill step, create/update task tracking for all steps and keep it synchronized as progress changes. > - User-question prompts mean to ask the user directly in Codex. > - Ignore Claude-specific mode-switch instructions when they appear. > - Strict execution contract: when a user explicitly invokes a skill, execute that skill protocol as written. > - Subagent authorization: when a skill is user-invoked or AI-detected and its protocol requires subagents, that skill activation authorizes use of the required `spawn_agent` subagent(s) for that task. > - Do not skip, reorder, or merge protocol steps unless the user explicitly approves the deviation first. > - For workflow skills, execute each listed child-skill step explicitly and report step-by-step evidence. > - If a required step/tool cannot run in this environment, stop and ask the user before adapting. ## Codex Project-Reference Loading (No Hooks) Codex uses static project-reference loading instead of runtime-injected project docs. When coding, planning, debugging, testing, or reviewing, open project docs explicitly using this routing. **Always read:** - `docs/project-config.json` (project-specific paths, commands, modules, and workflow/test settings) - `docs/project-reference/docs-index-reference.md` (routes to the full `docs/project-reference/*` catalog) - `docs/project-reference/lessons.md` (always-on guardrails and anti-patterns) **Missing/stale context route:** If `docs/project-config.json`, the docs index, `lessons.md`, `CLAUDE.md`, `AGENTS.md`, or any task-required reference doc is missing or stale, auto-run `$project-init` or the narrow setup route (`$project-config`, `$docs-init`, `$scan-all`, `$scan --target=`, `$claude-md-init`) before ordinary project-specific work. If Codex mirrors or `AGENTS.md` are missing/stale, ask the user to run `$sync-codex`; do not auto-run it. **Situation-based docs:** - Project structure/architecture/tech-stack/deployment/setup (any layer — backend, frontend, or infra): `project-structure-reference.md` - Backend/CQRS/API/domain/entity changes: `backend-patterns-reference.md`, `domain-entities-reference.md` - Frontend/UI/styling/design-system: `frontend-patterns-reference.md`, `scss-styling-guide.md`, `design-system/README.md` - Spec authoring, `docs/specs/` pathing, or TC format: `feature-spec-reference.md`, `spec-system-reference.md`, `spec-principles.md` - Behavior/public-contract changes or spec-test-code sync: `workflow-spec-test-code-cycle-reference.md` plus the spec docs above - Derived spec indexes/ERDs/reimplementation guides: `spec-system-reference.md` and source Feature Specs under `docs/specs/` - Integration test implementation/review: `integration-test-reference.md` - E2E test implementation/review: `e2e-test-reference.md` - Code review/audit work: `code-review-rules.md` plus domain docs above based on changed files Do not read all docs blindly. Start from `docs-index-reference.md`, then open only relevant files for the task. ## 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 by asking the user directly 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 by asking the user directly (`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 task tracking 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. task tracking Before Starting **MANDATORY IMPORTANT MUST ATTENTION** — Call task tracking for every step before beginning any work: ``` Task tracking: "Brainstorm → RICE opportunity map" [discovery mode] Task tracking: "Market research (web-research)" [discovery mode, conditional] Task tracking: "Deep research (deep-research)" [discovery mode, conditional; only when web-research ran] Task tracking: "Idea capture" Task tracking: "Refine to PBI" Task tracking: "Refinement rationale review (why-review after refine)" Task tracking: "Feature Spec draft (spec [mode=draft])" Task tracking: "Test specifications (spec [mode=tests])" Task tracking: "Test-spec rationale review (why-review after spec [mode=tests])" Task tracking: "Test specification review (artifact-review --type=spec-tests)" Task tracking: "Domain analysis (domain-analysis)" [if domain entities change] Task tracking: "Domain rationale review (why-review after domain-analysis)" Task tracking: "Implementation plan (plan)" Task tracking: "Plan review (plan-review)" Task tracking: "Plan validation (plan-validate)" Task tracking: "Plan rationale review (why-review after plan-validate)" Task tracking: "PBI review (artifact-review --type=pbi)" Task tracking: "User stories (story)" Task tracking: "Story rationale review (why-review after story)" Task tracking: "Story review" Task tracking: "Dev BA PIC challenge" Task tracking: "Definition of Ready gate" Task tracking: "PBI HTML mock-up" [if UI] Task tracking: "Prioritize" Task tracking: "Documentation synchronization (docs-update)" Task tracking: "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 invocation — 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` --- > **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. > **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 the current task list 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:** the current task list done, child phases created, parent linked when nested, first child marked `in_progress`. > **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. > **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` > **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. > > ```markdown > ## 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. > **[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. **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. **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. - **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. - **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. > **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 `spawn_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. - **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. > **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 `/.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. **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 `/.md`; a missing or malformed body is reported, never reconstructed. Overlays are ADDITIVE …(truncated)