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.

Summary:

• Detect the track first: Single-PBI Deep keeps spec/scenario/plan gates; Multi-Opportunity Discovery keeps one embedded decomposition context and skips the deep per-opportunity plan cycle.
• Apply the shared isLargeIdea rule before either track. When true, keep the complete large_idea_decomposition block in the PBI/spec outputs and aggregate it in the final presentation/mock-ups; do not create a roadmap file by default.
• Treat generated ideas, specs, PBIs, stories, and mockups as draft until their review/acceptance gates pass; finish with prioritized, dependency-aware backlog evidence.
• Every generated PBI MUST be one independently releasable actor-facing outcome with a complete entry-to-result journey; technical-only/foundation/setup work is enabling work under that outcome, never a standalone PBI.
• For UI PBIs, /pbi-mockup MUST produce a navigable mock app with every required page/view, navigation edge, common/domain/page component, applicable state, and full-flow demo — one isolated screen is a blocking failure.

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

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

• Main steps: detect mode → research/brainstorm as applicable → capture/refine → deep-only spec/test/scenario/plan gates → PBI/story review → challenge/DoR → UI mock-up/design-spec → prioritize → docs/presentation/handoff.

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 isLargeIdea = multipleIndependentOutcomes || ambiguousOrResearchHeavy || releaseScopeDecomposition || oversizedPbiThatMustSplit before either track. A true signal requires all five fields: outcome_slices, dependencies_order, non_goals, risks_evidence, and deferred_work_owner; all-false ideas omit the block. An existing supplied roadmap is read-only context; only an explicit roadmap-deliverable request enters the standalone writer.
• MUST ATTENTION run /scenario before the Single-PBI Deep plan only when the selected slice/decomposition needs adversarial replay, state, ownership, recovery, or evidence analysis; otherwise record the conditional skip with evidence. Multi-Opportunity Discovery skips it with the explicitly skipped per-opportunity plan cycle.
• 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 apply .claude/skills/shared/releasable-pbi-contract.md at refine, artifact review, DoR, story, and mockup handoffs; a blocked outcome cannot advance by assumption.
• 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] Large-idea decomposition gate — conditional: stable slice IDs, dependency order, non-goals, risks/evidence, and deferred-work owners in the owning PBI/spec
- [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
- [x] Scenario analysis (scenario)                  — SINGLE-PBI DEEP MODE ONLY: adversarial replay, persistence, state, access, recovery, and evidence cases before the plan; skip with the plan cycle in discovery 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; keep the decomposition gate and run /scenario only when the slice/risk context needs it. In discovery mode, run brainstorm before the PBI loop and preserve one shared decomposition context; deselect spec [mode=draft], spec [mode=tests], artifact-review --type=spec-tests, scenario, 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 (including the Releasable Outcome Gate) → /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. UI PBIs MUST carry the page/view, navigation, component, state, and full-flow evidence required by the shared releasable-PBI contract.

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: "Releasable Outcome Gate (inside refine)"
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.

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:

6. Artifact Locations

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

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 -> /scenario -> /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 selected step MUST ATTENTION invoke its Skill tool — marking a selected task completed without skill invocation is a workflow violation. A declared conditional or mode-gated step may be marked skipped only with evidence and an explicit reason; 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 → /scenario → /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
• /scenario — run for a selected slice when its risks need adversarial replay/state/ownership/recovery/evidence analysis; otherwise mark the conditional skip with evidence
• /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 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.

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 and record Run ID, Task ID, Attempt ID, target scope, and target fingerprint.
2. After each file/section reviewed: Append findings, evidence, changed paths, and gaps immediately — never hold them in memory.
3. Delegated return: A sub-agent emits only the structured SYNC:subagent-return-contract envelope with exact totals, salient Critical/High findings (maximum ten), current attempt, and Full report: path. Inline user-facing output: Preserve the skill's requested explanation or teaching, with links to the persisted evidence; the delegated transport limit does not replace that deliverable. Do not paste a full review report into an envelope.
4. Parent synthesis: The main agent reads the full report for synthesis, acceptance, deduplication, and repair planning — not only when a named blocker exists. It preserves all severities beyond the transport cap.
5. Read-only boundary: A read-only leaf may write its report/repair proposal but MUST NOT edit source, generated output, or user data; the parent/owner performs repairs after acceptance.
6. Advancement gate: The parent records ACCEPTED for the current Attempt ID only after reconciling target, totals, gaps, and changed paths; stale or late attempts cannot advance dependent work.

Why: Context cutoff mid-execution loses ALL in-memory findings. Each disk write survives compaction. Partial results are better than no results, while explicit identity prevents a late result from being mistaken for the current run.

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 the structured envelope below. Main agent reads the envelope first, then opens the referenced report for synthesis, acceptance, deduplication, or repair planning; a full report is never pasted inline.

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

Status: ✅ PASS | ⚠️ PARTIAL | ❌ FAIL
Confidence: [0-100]%
Run ID: [stable run identifier]
Task ID: [parent task or phase identifier]
Attempt ID: [monotonic attempt/revision identifier]
Target: [exact files/paths or scope] @ [target fingerprint/commit]
Changed paths: [none | exact paths]
Finding totals: Critical=[n] | High=[n] | Medium=[n] | Low=[n]
Acceptance: PENDING | ACCEPTED | REJECTED — parent records the decision

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

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

### Gaps / Unverified

- [missing host, runtime, coverage, or evidence limitation]

### Actions Taken

- [file changed] [what changed]

### Blockers (if any)

- [blocker description, or `none`]

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

The ten-bullet limit is a transport limit, not a visibility limit: the full report may contain more than ten Medium/Low findings when no named blocker exists, and the parent MUST read it when synthesizing or deduplicating. The parent MUST reject a stale, duplicate, or superseded Attempt ID and MUST accept the current attempt before advancing a dependent step. Read-only leaves write repair proposals/reports only; they do not edit source, generated carriers, or user files.

Context budget — the return payload is a SUMMARY, not a transcript: no raw file contents / full diffs / verbatim logs inline, no re-pasted source. Everything beyond the envelope lives in the incrementally-written report. A sub-agent that would exceed the summary shape MUST persist the detail and return only the pointer; bounded transport must never become bounded visibility.

[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 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

…(truncated)