Feature Presentation

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=<key>, $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.

[BLOCKING] Execute skill steps in declared order. NEVER skip, reorder, or merge steps without explicit user approval. [BLOCKING] Before each step or sub-skill call, update task tracking: set in_progress when step starts, set completed when step ends. [BLOCKING] Every completed/skipped step MUST include brief evidence or explicit skip reason. [BLOCKING] If Task tools are unavailable, create and maintain an equivalent step-by-step plan tracker with the same status transitions.

Quick Summary

Goal: Synthesize every session-generated idea, Feature Spec, PBI, user story, design-spec, and mockup into ONE standalone HTML slide deck for PO/BA/Dev/QC — project-faithful styling, an interactive MVP demo of every main user journey, vanilla-JS slide engine — so the whole team reviews the feature from a single offline file before build.

Summary:

• Purpose / altitude: a SYNTHESIS deck at a higher altitude than pbi-mockup — accumulates many artifacts (ideas + specs + PBIs + stories + design-specs + mockups) into ONE stakeholder presentation, not one PBI's UI preview.
• Main steps (read-this-if-nothing-else): (1) resolve scope on activePlan created→now range → (2) gap-fill missing PBIs/mockups via SUB-AGENT → (3) load project design context → (4) [BLOCKING] inventory existing UI + map flows → (5) accumulate + extract main-story journeys (one todo each) → (6) assemble ONE standalone HTML deck → (7) save → (8) [BLOCKING] fidelity gate (incl. demo integrity) + (8b) Demo-Quality review → (9) report.
• Output: exactly ONE self-contained HTML file at team-artifacts/presentations/{YYMMDD}-presentation-{slug}.html — inline CSS/JS, Google Fonts only, NO CDN (no reveal.js); a ~60-line vanilla-JS slide engine (keyboard ←/→/Home/End, nav dots, counter, light/dark toggle).
• Interactive demo + mockup reuse: every in-scope main user story is an interactive MVP demo slide ("click X → see Y → move to Z") with a plain-language narration strip + a "How to drive this demo" guide slide near the top; existing team-artifacts/pbis/*-mockup.html are REUSED (never regenerated), embedded via <iframe srcdoc="…entity-escaped…"> (escaping rule in references/deck-template.md) — the mock-up is self-driving, the deck adds only narration; journeys are planned as an ordered list (Step 5, one todo each) and signed off by the final Demo-Quality review (Step 8b).
• Spec-only branch: idea-to-spec degrades to design-spec visuals (ASCII wireframes + inventory/states/tokens tables) + a narrated step-through of ASCII frames — NO HTML mockups, NO pbi-mockup invocation — preserving the spec-only contract; full HTML mockups appear only in idea-to-pbi.

Workflow:

1. Resolve scope — anchor on activePlan, accumulate its full artifact set across the plan's created→now date range (every {YYMMDD} in range, NOT just today); custom prompt widens; standalone + no prompt → ask the user directly.
2. Gap-fill (smart routing — sub-agent) — spec lacks PBIs → workflow-spec-to-pbi AS A SUB-AGENT; PBIs lack mockups (mockup-bearing workflow) → pbi-mockup. Spec-only idea-to-spec → SKIP mockup generation.
3. Load project design context — baseline + matched per-app design-system docs via project-config.json.
4. [BLOCKING] Inventory existing UI + map connected flows — SYNC:existing-ui-research.
5. Accumulate + structure content (incl. journey extraction) — parse each artifact into stakeholder sections; extract the main-story flows into an ordered journey list + task tracking one todo per journey; REAL domain data, never Lorem (references/artifact-accumulation.md).
6. Assemble ONE standalone HTML deck — inline CSS (design tokens, BEM) + vanilla-JS engine + a "How to drive this demo" guide slide + one interactive demo-flow slide per journey (embedded mockup + narration strip) + <iframe srcdoc> mockup embeds; spec-only path renders ASCII/tables + narrated ASCII frames; empty-state slide when no visual exists (references/deck-template.md).
7. Save → team-artifacts/presentations/{YYMMDD}-presentation-{slug}.html.
8. [BLOCKING] Fidelity gate (incl. demo integrity) — validate deck visuals + every journey clicks through vs Step 4 inventory; record Fidelity vs existing UI: PASS|FAIL (references/deck-template.md). 8b. [BLOCKING] Demo-Quality review — final stakeholder-comprehension pass; record Demo quality: PASS|FAIL.
9. Report — path, artifact count synthesized, demo journeys, stakeholder sections, fidelity + demo-quality verdicts.

Key Rules:

• Emit exactly ONE self-contained HTML file; inline CSS/JS; no external <script src> / <link rel=stylesheet> except Google Fonts; no CDN reveal.js — vanilla-JS engine only.
• Present every in-scope main user story as an interactive MVP demo slide (embedded interactive mockup + narration strip); plan journeys first (Step 5, one todo each), sign off with the Demo-Quality review (Step 8b).
• Embed existing -mockup.html via <iframe srcdoc> — never regenerate a mockup that already exists; the mock-up is self-driving, the deck adds only narration.
• Spec-only idea-to-spec → design-spec ASCII wireframes + inventory/states/tokens tables + narrated ASCII-frame step-through ONLY; never generate HTML mockups, never invoke pbi-mockup.
• Use REAL domain entity field names + realistic sample data — never Lorem ipsum or "Item 1, Item 2".
• Empty-state slide when an in-scope feature has no mockup AND no design-spec — never a broken/blank iframe.
• Run gap-fill multi-step workflows as SUB-AGENTS (summary returned + findings written to plans/reports/) per CLAUDE.md "Workflow Step Advancement §3".
• Keep accompanying prose/captions tech-agnostic (business/observable terms, not framework/CSS class names); the rendered HTML may use real class names internally.

Be skeptical. Apply critical thinking, sequential thinking. Every claim needs traced proof, confidence percentages (Idea should be more than 80%).

Feature Presentation — Stakeholder HTML Slide Deck

Synthesize all session-generated specs, PBIs, ideas, and mockups into one standalone HTML slide presentation for PO/BA/Dev/QC.

When to Use

• Near the end of workflow-idea-to-pbi and workflow-idea-to-spec, to present the whole feature set to stakeholders.
• Standalone, when a PO/BA/Dev/QC needs one offline deck synthesizing a feature's ideas, specs, PBIs, stories, and mockups.

NOT for: Generating a single PBI's UI preview (use $pbi-mockup), authoring a Feature Spec (use $spec), or producing a design spec (use $design-spec).

Quick Reference

Input

Output

Related

• Input from: $spec, $refine, $story, $pbi-mockup, $design-spec
• Command: $feature-presentation
• Detail: references/deck-template.md (HTML scaffold + slide engine + iframe-srcdoc escaping + fidelity gate); references/artifact-accumulation.md (scope resolution + per-type parse map + gap-fill + branches)

Detailed Workflow

Step 1: Resolve Scope

Determine which artifacts the deck synthesizes. See references/artifact-accumulation.md → "Scope Resolution" for the full algorithm.

1. Default (active-plan anchor): Read activePlan from /tmp/ck-session-{id}.json (set by .claude/scripts/set-active-plan.cjs). Accumulate the plan's FULL artifact set across the plan's created→now date range — glob team-artifacts/{ideas,pbis,pbis/stories,design-specs} and *-mockup.html for EVERY {YYMMDD} in that range, plus the plan's docs/specs outputs.
   • Multi-day rule: a workflow that spans midnight authors specs on day 1 and PBIs on day 2 — a single-day {YYMMDD} glob silently drops day-1 artifacts. Glob over the whole created→now range, never just today.
2. Custom prompt: If the user names specs/features, widen scope to those named artifacts (plus their dependents).
3. Standalone + no prompt: Use ask the user directly to ask which specs/ideas to present — never silently guess scope.

Step 2: Gap-Fill (Smart Routing — Sub-Agent)

Fill missing downstream artifacts so the deck is complete. See references/artifact-accumulation.md → "Gap-Fill Routing".

1. Spec lacks PBIs: Invoke workflow-spec-to-pbi AS A SUB-AGENT (spawn_agent tool) — per CLAUDE.md "Workflow Step Advancement §3", a step that activates a multi-step workflow MUST run as a sub-agent: it returns only a summary and writes full findings to plans/reports/. This keeps the deck-build context bounded.
2. PBIs lack -mockup.html AND the workflow is mockup-bearing (idea-to-pbi): Invoke pbi-mockup per PBI to generate the missing mockup.
3. Spec-only idea-to-spec context: SKIP all mockup generation — never invoke pbi-mockup. The deck will use design-spec visuals only (Step 6 spec-only path). This preserves the idea-to-spec no-mockup contract.

Step 3: Load Project Design Context

The deck CSS must use the project's design tokens (same discovery as pbi-mockup):

1. Mandatory baseline: Read docs/project-reference/design-system/README.md and docs/project-reference/design-system/design-system-canonical.md.
2. Primary: Read top-level designSystem in docs/project-config.json — use designSystem.docsPath + designSystem.canonicalDoc, then match the presented feature/app context against designSystem.appMappings[] to select the per-app doc.
3. Fallback: Glob("docs/project-reference/design-system/*.md") → case-insensitive substring match on app/feature name. Default: README.md.
4. Extract colors, typography, spacing, border-radius, shadows → these become the deck's CSS variables.

Step 4: [BLOCKING] Inventory Existing UI + Map Connected Flows

[BLOCKING] Do NOT assemble the deck until this inventory + connected-flow map is done (canonical: SYNC:existing-ui-research). The deck must faithfully match the current UI system, not generic HTML.

1. Read docs/project-reference/frontend-patterns-reference.md (first 200 lines) — base component classes, form/table/dialog patterns.
2. Sample 2-3 real shared/module components for layout patterns and CSS class naming.
3. Map the connected feature flows the presented features link to/from, so the deck's embedded visuals fit the surrounding navigation.

Step 5: Accumulate + Structure Content (incl. journey extraction — think → plan → many todos)

Parse each in-scope artifact into stakeholder-oriented slide sections (see Slide Taxonomy). See references/artifact-accumulation.md → "Per-Artifact-Type Parse Map" for which artifact maps to which section.

• Use REAL domain entity field names + realistic sample data from docs/project-reference/domain-entities-reference.md — never Lorem ipsum or "Item 1, Item 2".
• Keep accompanying prose/captions tech-agnostic (business/observable terms, not framework/CSS class names).
• Extract each PBI's priority/rank — read the priority label + numeric rank from each PBI's frontmatter (and the ranked-order backlog artifact team-artifacts/backlog/*-backlog.md when present). The Scope & backlog slide MUST display PBIs in ranked order with a priority label per PBI card — the deck carries the same priority info the backlog and mockups do. If PBIs lack priority, note it explicitly rather than dropping the field.
• Extract the main-story / MVP flows into an ordered journey list — from PBI ## Acceptance Criteria GIVEN/WHEN/THEN + story "As a / I want / So that" + each mock-up's flow-specs (references/artifact-accumulation.md §6 Journey-Extraction Map). One journey per main user story (MVP happy path), each an ordered sequence: entry → click steps ("click X → see Y → move to Z") → end state + one plain-language explanation per step. When a -mockup.html exists, reuse its flow-specs verbatim so the deck demo == the per-PBI prototype.
• task tracking one todo per journey slide — so each journey is assembled (Step 6) and later verified (Step 8 demo integrity / final demo-quality review) individually. (The "think → plan → many todos before do".)

Step 6: Assemble ONE Standalone HTML Deck

Build the single self-contained HTML file from the scaffold in references/deck-template.md:

• Inline <style> — design tokens as CSS variables, BEM class names, light/dark themes.
• Vanilla-JS slide engine — keyboard ←/→/Home/End, nav dots, slide counter, theme toggle (no CDN reveal.js). Don't hijack arrow keys while a demo iframe is focused; OPTIONAL postMessage('play') to auto-start a journey degrades gracefully (references/deck-template.md §3b engine-coexistence note).
• "How to drive this demo" guide slide near the top — teach the viewer how to click hotspots and use each demo's own ▶ Play / ⏮ ⏭ / ↺ Reset controls (inside the mock-up) to walk a journey, and ←/→ to change slides, so a non-technical stakeholder is never lost (references/deck-template.md §3b).
• Demo-flow slides (one per journey from Step 5): each embeds the interactive pbi-mockup HTML scoped to that flow via <iframe srcdoc="…escaped…"> and overlays a deck-level narration/explanation strip (current step + plain-language explanation, text only + "⚠ Simulated" note). The journey's ▶/⏮/⏭/↺ controls live INSIDE the embedded mock-up — it is self-driving; the deck adds only narration and does NOT re-implement or duplicate those controls (references/deck-template.md §3b).
• Mockup-bearing path (idea-to-pbi): embed each existing -mockup.html via <iframe srcdoc="…escaped…"> — the entity-escaping rule (&-first, escape-once-unconditionally) is in references/deck-template.md. Never regenerate a mockup that already exists.
• Spec-only path (idea-to-spec): render the design-spec ASCII wireframes + Component Inventory / States / Design-Tokens tables instead of HTML mockups; the journey demo is a narrated step-through of design-spec ASCII frames advanced by Next, each with its step explanation. NO <iframe srcdoc> mockup embed, NEVER invoke pbi-mockup.
• Empty-state (F3): when an in-scope feature has NO -mockup.html AND NO design-spec, render an explicit empty-state slide ("No mockup/design-spec available for {feature}") — never a broken/blank iframe.

Step 7: Save

• Path: team-artifacts/presentations/{YYMMDD}-presentation-{slug}.html (create the presentations/ dir if absent).
• {slug} = the presented feature(s) or plan slug.

Step 8: [BLOCKING] Fidelity Validation — Deck Matches Existing UI

[BLOCKING] After the deck is assembled, validate its visuals faithfully match the existing UI inventoried in Step 4 before handoff. Do NOT report the deck as done until this validation records a result. Full procedure: references/deck-template.md → "[BLOCKING] Fidelity Gate".

The fidelity gate also covers demo integrity — every journey/demo slide clicks through end-to-end inside its iframe (each step reaches its end state via real hotspots); no dead controls; the narration strip names the current step + explanation and stays tech-agnostic (M1/M2); the "⚠ Simulated" note is visible; spec-only journeys advance their narrated ASCII frames.

Record the outcome in the Step 9 report:

Fidelity vs existing UI: PASS | FAIL — tokens / components / layout / flows / embeds / demos matched? If FAIL: what diverged + the fix.

If FAIL, revise the deck to match the existing UI and re-validate before handoff.

Step 8b: [BLOCKING] Demo-Quality Review (final review todo)

[BLOCKING] Final review before the report (the per-journey todos and this gate were created in Step 5). First confirm the deck SATISFIES the intent: every in-scope main user story is presented as a journey (coverage — no main story missing) AND each journey faithfully conveys that story's intended behavior, not merely that slides render. Then run a stakeholder-comprehension pass: could a PO with no prior context follow each journey end-to-end? Confirm every demo-flow slide clicks through, narration explains each step in plain language, the "⚠ Simulated" note is present, and the spec-only path degrades to narrated ASCII frames (never an HTML mockup). Record Demo quality: PASS | FAIL — FAIL if any main story is unrepresented or misrepresented, regardless of polish.

If FAIL, fix the journey slides (re-extract from the §6 journey map / re-embed the flow-scoped mockup) and re-review before handoff.

Step 9: Report to User

After assembly, output:

Deck generated: team-artifacts/presentations/{YYMMDD}-presentation-{slug}.html
- Artifacts synthesized: {count} ({ideas}/{specs}/{pbis}/{stories}/{mockups}/{design-specs})
- Backlog priority: {ranked | not prioritized} — Scope & backlog slide shows {N} PBIs in ranked order with priority labels
- Demo journeys: {count} ({journey titles})
- Stakeholder sections: {title, how-to-demo, business-context, scope-backlog, behavior-rules, demo-flows, ui-mockups, qc-view, summary}
- Fidelity vs existing UI: PASS | FAIL
- Demo quality: PASS | FAIL

Open in browser to preview. Click highlighted hotspots or press ▶ Play to walk a journey; use ←/→ or nav dots to move between slides; theme toggle for light/dark.

Slide Taxonomy (stakeholder-oriented)

Every slide section must serve the four stakeholder audiences (PO/BA/Dev/QC):

UI Layout

The deck is itself a UI artifact. ASCII of a slide frame:

┌────────────────────────────────────────────────┐
│ ◀  Feature Presentation — {Feature}     3 / 12  │  ← top bar: title + counter
├────────────────────────────────────────────────┤
│  ## Business Context                            │
│  • Problem  • Value  • Epics                     │  ← slide body (design-system tokens)
│  ┌──────────────────────────────────────────┐   │
│  │  <iframe srcdoc> embedded mockup / wire   │   │  ← embedded visual (or empty-state)
│  └──────────────────────────────────────────┘   │
├────────────────────────────────────────────────┤
│  ● ● ● ○ ○ ○ ○ ○ ○ ○ ○ ○        ◀ Prev  Next ▶  │  ← nav dots + buttons (vanilla JS)
└────────────────────────────────────────────────┘

Component tiers: common (slide shell, nav) — domain-shared (mockup/wireframe embed block) — page-app (per-artifact content slides). Keyboard ←/→, Home/End; theme toggle (light/dark) reusing design-system tokens.

Edge Cases

Anti-Patterns

Alternatives Considered

1. Extend pbi-mockup with a --deck mode (rejected) — pbi-mockup is per-PBI and mockup-scoped; a multi-artifact synthesis deck has a different input set and audience. Overloading one skill raises change cost and blurs the spec-only contract. Separate skill keeps each single-responsibility.
2. CDN reveal.js / impress.js slide framework (rejected) — violates the self-contained/no-external-deps contract (offline-break, supply-chain surface, new dependency). Vanilla-JS engine is ~60 lines, matches pbi-mockup's zero-dep posture.
3. Link to mockup files instead of inlining (rejected) — breaks the "ONE standalone html file" mandate; a moved/un-co-located deck renders broken. <iframe srcdoc> keeps everything in one file.
4. Chosen: standalone skill + inline single-file deck + iframe-srcdoc mockup embed. Con: deck file size grows with embedded mockups — acceptable (HTML is text, gzips well; offline portability outweighs size).

Design Rationale

A synthesis deck is a different artifact at a different altitude than a per-PBI mockup, so it earns its own skill — but it must NOT duplicate the mockup engine (reuse/embed). <iframe srcdoc> is the one mechanism satisfying BOTH "single standalone file" AND "reuse existing mockups" without re-rendering. Carrying SYNC:existing-ui-research + the fidelity gate is what makes the deck project-faithful rather than generic. The spec-only branch + empty-state slide preserve the idea-to-spec no-mockup contract while still giving stakeholders a visual. Running gap-fill sub-workflows as sub-agents keeps the deck-build context bounded — the deck skill consumes a summary, not the full workflow transcript.

Security Considerations

<iframe srcdoc> embeds first-party generated mockup HTML only — no remote content, no user-supplied script. Entity-escaping the embedded mockup into srcdoc is also a safety boundary: it prevents an unescaped </iframe>/<script> in a mockup from breaking out of the embed. The deck opens offline (no network except the Google Fonts CSS). No secrets in artifacts.

Workflow Recommendation

MANDATORY IMPORTANT MUST ATTENTION — NO EXCEPTIONS: If you are NOT already in a workflow, you MUST ATTENTION use ask the user directly to ask the user. Do NOT judge task complexity or decide this is "simple enough to skip" — the user decides whether to use a workflow, not you:

1. Activate workflow-idea-to-pbi workflow (Recommended) — includes the presentation deck as a late step.
2. Activate workflow-idea-to-spec workflow — spec-only path; deck degrades to design-spec visuals.
3. Execute $feature-presentation directly — run this skill standalone on existing artifacts.

Next Steps

MANDATORY IMPORTANT MUST ATTENTION — NO EXCEPTIONS after completing this skill, you MUST ATTENTION use ask the user directly to present these options. Do NOT skip because the task seems "simple" or "obvious" — the user decides:

• "Open the deck" — open the standalone HTML in a browser to review with stakeholders
• "$prioritize" — prioritize the synthesized PBIs in the backlog
• "$plan" — start implementation planning
• "Skip, continue manually" — user decides

[IMPORTANT] Use task tracking to break ALL work into small tasks BEFORE starting.

Evidence Gate: MANDATORY IMPORTANT MUST ATTENTION — every claim, finding, and recommendation requires file:line proof or traced evidence with confidence percentage (>80% to act, <80% must verify first).

[BLOCKING] Understand the existing UI before you design or spec a new/updated screen. Before producing any wireframe, mockup, screen design, or UI spec:

1. Inventory existing related UI — search the project for screens, pages, and components already serving this feature or its domain (consult design-system docs + the real component inventory).
2. Map connected flows — identify every feature that links to, embeds, includes, or navigates to/from the new screen; trace its entry and exit flows so the new screen fits them.
3. Reuse before invent — prefer existing components, patterns, and layout conventions; justify any new component against what already exists.
4. Record findings — note the matched existing screens/components + connected flows in the artifact so downstream design faithfully matches the current UI system.

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

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.

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.

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.

Prompt-Enhance Closing Anchors

IMPORTANT MUST ATTENTION follow declared step order for this skill; NEVER skip, reorder, or merge steps without explicit user approval IMPORTANT MUST ATTENTION for every step/sub-skill call: set in_progress before execution, set completed after execution IMPORTANT MUST ATTENTION every skipped step MUST include explicit reason; every completed step MUST include concise evidence IMPORTANT MUST ATTENTION if Task tools unavailable, maintain an equivalent step-by-step plan tracker with synchronized statuses

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

…(truncated)