Watzup

<!-- PROMPT-ENHANCE:STEP-TASK-ANCHOR:START -->

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

<!-- PROMPT-ENHANCE:STEP-TASK-ANCHOR:END -->

Quick Summary

Goal: Hand the developer a complete, evidence-backed wrap-up — by reviewing current branch changes and summarizing impact/​quality — with a change summary, doc/​spec staleness flags, root-cause lessons, and a /​understand explanation, WITHOUT mutating any file, so they decide the next step from full context.

Workflow:

1. Review — Analyze recent commits: what was modified, added, removed
2. Summarize — Provide detailed change summary with quality assessment
3. Doc Check — Cross-reference changed files against docs/ for staleness
4. Lesson Learned — Analyze AI mistakes/​issues during the task and capture lessons
5. Understand Handoff — Invoke /​understand as the final mandatory task so the developer gets a Purpose → How → Why explanation of the completed work

Key Rules:

• READ-ONLY: only flag findings, never implement or fix anything
• Doc staleness check is REQUIRED (see mapping table below)
• Lesson-learned analysis is REQUIRED (see section below)
• Final review task MUST ATTENTION include doc-staleness check, lesson-learned analysis, AND the final /​understand handoff
• MUST ATTENTION call /​understand after the watzup summary/​doc/​mistake analysis and before the final Next Steps prompt

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

Review my current branch and the most recent commits. Provide a detailed summary of all changes, including what was modified, added, or removed. Analyze the overall impact and quality of the changes.

IMPORTANT: Review and summarize only, never start implementing.

---

Doc Staleness Check (REQUIRED)

After change summary, run git diff --name-only (against base branch or recent commits), cross-reference changed files against relevant docs:

Output one of:

• A bulleted list of docs that may need updating, with a brief note on what is likely stale (e.g., "hook count changed from 31 to 32").
• No doc updates needed — if no changed file pattern maps to a doc.

Do not edit docs during watzup. Only flag. The user decides whether to fix.

---

Spec-Driven Development Health Check (REQUIRED when business code changed)

Run this check when git diff --name-only includes ANY changes under the backend service source paths or frontend app/​domain source paths (resolve the concrete paths from the project's structure reference / docs/​project-config.json).

Step 1 — Feature Spec Root Check

ls docs/​specs/ 2>/​dev/​null

Note: Results are app-bucket names. To find a specific Feature Spec, probe ls docs/​specs/​{app-bucket}/ for canonical README.{Feature}.md files and derived bucket indexes/​ERDs.

Step 2 — Spec Staleness Check (only if bundle exists)

For each spec file in docs/​specs/:

git log --since="30 days ago" --name-only -- docs/​specs/ | head -10

Step 3 — Feature Docs Freshness Check

git log --since="30 days ago" --name-only -- docs/​specs/ | head -10

Output only flags that apply. Skip this section entirely if no business code changed.

---

AI Mistake & Lesson Learned Analysis (REQUIRED)

After doc staleness check, review entire session for AI mistakes and lessons learned.

Step 1 — Surface all mistakes

List every error made during session. For each, note:

• What happened (observable symptom — build fail, test fail, wrong output)
• Where it happened (file:line if applicable)

Common mistake categories:

• Assumed an API/​type/​enum value existed without reading the source
• Assumed infrastructure availability without checking requirements
• Conflated "code exists" with "code executes" — missed path tracing
• Used a pattern without verifying the new context has the same preconditions
• Reported "done" without verifying ALL affected outputs across all stacks
• Hallucinated method names, class names, or file paths

Step 2 — Extract root-cause lessons (NOT symptom fixes)

For each mistake, apply this 3-step extraction:

2a. Name the failure mode — NOT the symptom, the reasoning failure:

2b. Find the class — Where else could this SAME failure mode strike?

If failure mode applies in only one specific file or case → go up one abstraction level until it generalizes. Good lesson applies to ≥3 different contexts.

2c. Write as a universal rule — Strip ALL project-specific names:

• No file paths, class names specific to this codebase, or tool names
• Must read as useful advice on a completely different codebase in a different language
• If multiple mistakes share the same failure mode → consolidate into ONE lesson
• Test: "Would this prevent the same class of mistake in a Java, Go, or Python project?" If yes → good. If no → rewrite.

Step 3 — Ask user to persist

"Found [N] root-cause lesson(s). Should I use /​learn to save them for future sessions?"

Wait for user confirmation before invoking /​learn.

Output one of:

• A numbered list: failure mode → universal lesson → proposed /​learn text
• No AI mistakes identified in this session — if genuinely none found

Be honest and self-critical. Surface-level symptom fixes ("always check file X") applying only to this codebase are NOT lessons — they are noise. Purpose: root-cause prevention compounding across sessions.

---

Next Steps

MANDATORY IMPORTANT MUST ATTENTION — NO EXCEPTIONS before presenting these options, invoke /​understand as the final mandatory todo task using the watzup summary and current change set as scope. If /​understand is unavailable, stop and report that blocker instead of silently skipping the handoff.

After /​understand completes, MUST ATTENTION use AskUserQuestion to present these options. NEVER skip because task seems "simple" or "obvious" — the user decides:

• "/​workflow-end (Recommended)" — Complete and close the active workflow
• "/​commit" — Commit changes if not using workflow
• "Skip, continue manually" — user decides

[IMPORTANT] Use TaskCreate to break ALL work into small tasks BEFORE starting — including tasks for each file read. This prevents context loss from long files. For simple tasks, AI MUST ATTENTION ask user whether to skip.

External Memory: For complex or lengthy work (research, analysis, scan, review), write intermediate findings and final results to a report file in plans/​reports/ — prevents context loss and serves as deliverable.

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).

<!-- SYNC:nested-task-creation -->

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

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

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

<!-- /​SYNC:nested-task-creation --> <!-- SYNC:project-reference-docs-guide -->

Project Reference Docs Gate — Run after task-tracking bootstrap and before target/​source file reads, grep, edits, or analysis. Project docs override generic framework assumptions.

1. Identify scope: file types, domain area, and operation.
2. Required docs by trigger: always docs/​project-reference/​lessons.md; doc lookup docs-index-reference.md; review code-review-rules.md; backend/​CQRS/​API backend-patterns-reference.md; domain/​entity domain-entities-reference.md; frontend/​UI frontend-patterns-reference.md; styles/​design scss-styling-guide.md + design-system/​design-system-canonical.md; integration tests integration-test-reference.md; E2E e2e-test-reference.md; feature docs/​specs feature-spec-reference.md + spec-system-reference.md + spec-principles.md; behavior/​public-contract/​spec-test-code sync workflow-spec-test-code-cycle-reference.md; derived spec index/​ERD/​reimplementation guides spec-system-reference.md + source Feature Specs under docs/​specs/; architecture/​new area project-structure-reference.md.
3. Read every required doc. 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 lower-level 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.
4. Before target work, state: Reference docs read: ... | Not applicable: ....

Ready when: scope evaluated, required docs checked/​read or setup route completed, lessons.md confirmed, citation emitted.

<!-- /​SYNC:project-reference-docs-guide --> <!-- SYNC:task-tracking-external-report -->

Task Tracking & External Report Persistence — Bootstrap this before execution; then run project-reference doc prefetch before target/​source work.

1. Create a small task breakdown before target file reads, grep, edits, or analysis. On context loss, inspect the current task list first.
2. Mark one task in_progress before work and completed immediately after evidence; never batch transitions.
3. For plan/​review work, create plans/​reports/​{skill}-{YYMMDD}-{HHmm}-{slug}.md before first finding.
4. Append findings after each file/​section/​decision and synthesize from the report file at the end.
5. Final output cites Full report: plans/​reports/​{filename}.

Blocked until: task breakdown exists, report path declared for plan/​review work, first finding persisted before the next finding.

<!-- /​SYNC:task-tracking-external-report --> <!-- SYNC:critical-thinking-mindset -->

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

<!-- /​SYNC:critical-thinking-mindset --> <!-- SYNC:evidence-based-reasoning -->

Evidence-Based Reasoning — Speculation is FORBIDDEN. Every claim needs proof.

1. Cite file:line, grep results, or framework docs for EVERY claim
2. Declare confidence: >80% act freely, 60-80% verify first, <60% DO NOT recommend
3. Cross-service validation required for architectural changes
4. "I don't have enough evidence" is valid and expected output

BLOCKED until: - [ ] Evidence file path (file:line) - [ ] Grep search performed - [ ] 3+ similar patterns found - [ ] Confidence level stated

Forbidden without proof: "obviously", "I think", "should be", "probably", "this is because" If incomplete → output: "Insufficient evidence. Verified: [...]. Not verified: [...]."

<!-- /​SYNC:evidence-based-reasoning --> <!-- SYNC:ai-mistake-prevention -->

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.

<!-- /​SYNC:ai-mistake-prevention --> <!-- SYNC:evidence-based-reasoning:reminder -->

IMPORTANT MUST ATTENTION cite file:line evidence for every claim (confidence >80% to act). NEVER speculate without proof.

<!-- /​SYNC:evidence-based-reasoning:reminder --> <!-- SYNC:critical-thinking-mindset:reminder -->

MUST ATTENTION apply critical thinking — every claim needs traced proof, confidence >80% to act. Anti-hallucination: never present guess as fact.

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

MUST ATTENTION apply AI mistake prevention — holistic-first debugging, fix at responsible layer, surface ambiguity before coding, re-read files after compaction.

<!-- /​SYNC:ai-mistake-prevention:reminder --> <!-- SYNC:task-tracking-external-report:reminder -->

• MANDATORY Bootstrap task tracking before target work; transition one task at a time.
• MANDATORY Persist plan/​review findings to plans/​reports/ incrementally and synthesize from disk.

<!-- /​SYNC:task-tracking-external-report:reminder --> <!-- SYNC:project-reference-docs-guide:reminder -->

• MANDATORY After task-tracking bootstrap and before target/​source work, read required project-reference docs and cite Reference docs read: ....
• MANDATORY Always include lessons.md; project conventions override generic defaults.
• MANDATORY If project config, root instruction files, or any required reference doc is missing, stop and run or ask the user to run /​project-init.

<!-- /​SYNC:project-reference-docs-guide:reminder --> <!-- SYNC:nested-task-creation:reminder -->

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

<!-- /​SYNC:nested-task-creation:reminder --> <!-- PROMPT-ENHANCE:STEP-TASK-CLOSING:START -->

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

<!-- PROMPT-ENHANCE:STEP-TASK-CLOSING:END -->

Closing Reminders

IMPORTANT MUST ATTENTION Goal: Hand the developer a complete, evidence-backed wrap-up — change summary, doc/​spec staleness flags, root-cause lessons, and a /​understand explanation — WITHOUT mutating any file, so they decide the next step from full context. MANDATORY IMPORTANT MUST ATTENTION stay READ-ONLY — only flag findings, NEVER implement or fix anything during watzup — why: watzup is a review/​handoff, not an edit pass. MANDATORY IMPORTANT MUST ATTENTION break work into small todo tasks using TaskCreate BEFORE starting. MANDATORY IMPORTANT MUST ATTENTION validate decisions with user via AskUserQuestion — never auto-decide. MANDATORY IMPORTANT MUST ATTENTION add a final review todo task to verify work quality. MANDATORY IMPORTANT MUST ATTENTION invoke /​understand as the final watzup handoff before asking the Next Steps question. MANDATORY IMPORTANT MUST ATTENTION READ the following files before starting:

IMPORTANT MUST ATTENTION READ CLAUDE.md before starting

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