--- name: workflow-visualize version: 1.0.0 description: '[Workflow] Use when activating the Visual Diagram workflow for create visual excalidraw diagrams from codebase investigation or web research.' disable-model-invocation: true --- ## Quick Summary **Goal:** [Workflow] Trigger Visual Diagram workflow — create visual excalidraw diagrams from codebase investigation or web research. **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. - NEVER skip mandatory workflow or skill gates. --- **IMPORTANT MANDATORY Steps:** /scout -> /investigate -> /excalidraw-diagram -> /workflow-end > **[BLOCKING]** Each step MUST ATTENTION invoke its `Skill` tool — marking a task `completed` without skill invocation is a workflow violation. NEVER batch-complete validation gates. Activate the `visualize` workflow. Run `/workflow-start visualize` with the user's prompt as context. **Steps:** /scout → /investigate → /excalidraw-diagram → /workflow-end **[TASK-PLANNING]** Before acting, analyze task scope and systematically break it into small todo tasks and sub-tasks using TaskCreate. > **[IMPORTANT]** Analyze how big the task is and break it into many small todo tasks systematically before starting — this is very important. **IMPORTANT MANDATORY Steps:** /scout -> /investigate -> /excalidraw-diagram -> /workflow-end > **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. > **AI Mistake Prevention** — Failure modes to avoid on every task: > > **Check downstream references before deleting.** Deleting components causes documentation and code staleness cascades. Map all referencing files before removal. > **Verify AI-generated content against actual code.** AI hallucinates APIs, class names, and method signatures. Always grep to confirm existence before documenting or referencing. > **Trace full dependency chain after edits.** Changing a definition misses downstream variables and consumers derived from it. Always trace the full chain. > **Trace ALL code paths when verifying correctness.** Confirming code exists is not confirming it executes. Always trace early exits, error branches, and conditional skips — not just happy path. > **When debugging, ask "whose responsibility?" before fixing.** Trace whether bug is in caller (wrong data) or callee (wrong handling). Fix at responsible layer — never patch symptom site. > **Assume existing values are intentional — ask WHY before changing.** Before changing any constant, limit, flag, or pattern: read comments, check git blame, examine surrounding code. > **Verify ALL affected outputs, not just the first.** Changes touching multiple stacks require verifying EVERY output. One green check is not all green checks. > **Holistic-first debugging — resist nearest-attention trap.** When investigating any failure, list EVERY precondition first (config, env vars, DB names, endpoints, DI registrations, data preconditions), then verify each against evidence before forming any code-layer hypothesis. > **Surgical changes — apply the diff test.** Bug fix: every changed line must trace directly to the bug. Don't restyle or improve adjacent code. Enhancement task: implement improvements AND announce them explicitly. > **Surface ambiguity before coding — don't pick silently.** If request has multiple interpretations, present each with effort estimate and ask. Never assume all-records, file-based, or more complex path. > **Keep domain concepts out of generic/shared/infrastructure layers.** A reusable layer (shared library, framework, infra module) must reference NO consumer-specific domain concept — tenant/customer/product IDs, business entities, feature rules. The leak compiles and runs, so it passes review silently while coupling the "reusable" layer to one consumer. Push domain fields/logic down into the consumer via subclass or composition. > **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. - **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. ## Closing Reminders **IMPORTANT MUST ATTENTION** apply Phase 1 compression before structural enhancement; preserve semantic meaning. **IMPORTANT MUST ATTENTION** NEVER alter YAML frontmatter, code blocks, tables, or SYNC-tag bodies during optimization. **IMPORTANT MUST ATTENTION** keep evidence gates and mandatory workflow/skill steps explicit and enforceable. **IMPORTANT MUST ATTENTION** add a final review task to verify output quality and unresolved risks.