Wazzap

wazzap — Four-phase decision framework

A leadership-style decision loop that captures why a decision was made so you can audit the reasoning later.

/wazzap:up          → "What's up?"           High-level wish
/wazzap:real        → "What's really up?"    Drill into the real problem (Socratic)
/wazzap:approaches  → "Different ways"       3 distinct options with pros/cons
/wazzap:go          → "Let's go!"            Concrete plan + execution handoff

Each phase writes a markdown doc. All four docs + a manifest live in one folder per decision. The audit trail is the artifact.

When to use this skill

• User invokes any /wazzap* command
• User says "let's think this through", "I need to decide", "I'm not sure what to do about X"
• User wants the reasoning captured, not just the conclusion

Storage convention

Where decisions live:

1. If cwd is inside a git repo → <git-repo-root>/.wazzap/
2. Otherwise → ~/Documents/wazzap/
3. User can override with path=<custom-dir> on any command

Per-decision folder: <wazzap-root>/YYYY-MM-DD-<slug>/

.wazzap/2026-04-28-redesign-auth-flow/
├── MANIFEST.yml
├── up.md
├── real.md
├── approaches.md
└── go.md

Active pointer: <wazzap-root>/_active is a text file containing the active slug. All /wazzap:* phase commands write to whatever _active points to, unless slug=<other-slug> is passed.

Slug rules

• Format: YYYY-MM-DD-<kebab-case-name> (date in local TZ).
• Name = 3+ meaningful words distilled from the user's :up wish.
• If input is too sparse to form a meaningful slug ("fix it", "do the thing"), the agent uses its single allowed :up clarifier to ask for a slug rather than asking about the wish itself.
• Collisions: append -2, -3, etc. Never silently overwrite an existing folder.

Manifest schema

Every decision folder has MANIFEST.yml:

slug: 2026-04-28-redesign-auth-flow
title: Redesign auth flow                    # human-readable
started_at: 2026-04-28T15:00:00-04:00         # ISO 8601 with TZ
updated_at: 2026-04-28T15:42:00-04:00         # bump on every write
status: thinking                              # thinking | decided | executing | done | abandoned
status_reason: ""                             # required when status terminal (done/abandoned)
visibility: shared                            # shared | private
current_phase: real                           # up | real | approaches | go | done
completed_phases: [up]                        # ordered list
chosen_approach: ""                           # filled at end of :approaches
revisits: []                                  # see "Revisits" below
linked_commits: []                            # optional, manual
linked_prs: []                                # optional, manual
linked_pm_state: ""                           # optional, manual (e.g. .planning/pm/...)
notes: ""                                     # free-form

Status semantics:

• thinking — actively in :up / :real / :approaches
• decided — :approaches completed; chosen_approach set; no execution attempted (or execution deferred)
• executing — :go written, execution in progress
• done — execution finished; outcome captured in notes
• abandoned — explicitly walked away; status_reason required

Privacy

At :up time, decide visibility:

• shared (default for code/work decisions): MANIFEST.yml visibility: shared. Folder is committable.
• private (default for relationships, money, career, health, personal-strategic): MANIFEST.yml visibility: private. Agent appends .wazzap/<slug>/ to the repo's .gitignore.

If the topic looks personal/sensitive, ask once at :up:

"Should this decision be private (gitignored) or shared (committed)?"

Otherwise default to shared. User can change visibility later by editing MANIFEST.yml and re-running gitignore step.

Soft-gate behavior

Phases don't strictly require predecessors. When a phase runs without its expected predecessor doc:

1. Warn: "No real.md found in active session. Continue anyway?"
2. If user proceeds, write a stub for the missing predecessor (just title + "Skipped — picked up at on ") so the audit trail stays whole.
3. Log the skip in manifest.notes.

Never silently proceed without leaving evidence of the gap.

Revisits

Realistic flow: :up → :real → :approaches, then user realizes the real problem was different. Re-running :real should:

1. Append to existing real.md with a new section:

   ---
   ## Revisited 2026-04-29 09:00
   
   **Trigger:** [what made you come back]
   
   [new probing log + revised problem statement]
   

2. Log in manifest:

   revisits:
     - phase: real
       at: 2026-04-29T09:00:00-04:00
       reason: "Realized the problem was about onboarding, not auth"
   

3. Never overwrite the original content. The audit trail is preservation-first.

Command routing

Read the matching sub-skill before executing each phase command:

:list and :resume are simple enough to live here in the parent.

/wazzap (parent orchestrator)

Behavior depends on context:

• No args, no active decision → "Start a new one (/wazzap:up <wish>) or list past decisions (/wazzap:list)?"
• No args, active decision exists → Print active manifest summary (slug, status, current_phase, last update). Suggest the next phase.
• Free text after /wazzap → Treat as /wazzap:up <text> and offer to continue through all 4 phases with checkpoints between each. After each phase, ask: "Continue to :real / :approaches / :go, or stop here?"

/wazzap:list

List recent decisions across both repo-local .wazzap/ (if in a repo) and ~/Documents/wazzap/.

Output a table:

SLUG                                    STATUS      PHASE        AGE       TITLE
2026-04-28-redesign-auth-flow          thinking    real         15m       Redesign auth flow
2026-04-25-pricing-tiers-v2            decided     done         3d        Pricing tiers v2
2026-04-20-cofounder-1on1-cadence  🔒  executing   go           8d        1:1 cadence with co-founder

• 🔒 prefix on private decisions.
• Sort by updated_at desc.
• Default limit: 10. Add all=true to show everything, status=<x> to filter.

Implementation: read each subdirectory's MANIFEST.yml, format as table.

/wazzap:resume <slug>

1. Verify the slug exists.
2. Write the slug to <wazzap-root>/_active.
3. Print the manifest summary.
4. Suggest next action based on current_phase:
   • If up done → suggest /wazzap:real
   • If real done → suggest /wazzap:approaches
   • etc.
   • If done or abandoned → ask if user wants to revisit a phase or start something new.

Cross-cutting principles (apply to every phase)

1. Bump updated_at in the manifest on every write.
2. Append completed_phases when a phase finishes.
3. Update current_phase at the start of each phase.
4. Preserve over overwrite. Always.
5. One clarifying question budget per phase (except :real which is Socratic by design). Don't ladder questions when one would do.
6. Mode discipline: :up = intake, :real = Socratic, :approaches = divergent generation + comparison, :go = plan + handoff. Don't bleed Socratic style into :up or autonomous one-shot into :real.
7. Vertical slicing in :go. The plan must be organized into 2–5 self-contained slices that each (a) cut top-to-bottom, (b) have a user-observable outcome, (c) trace to ≥1 success criterion from real.md, and (d) are independently shippable. One slice = one issue/ticket on handoff. Never horizontal (all schema → all API → all UI → integrate). See commands/go/SKILL.md for the slice template.

First action on any /wazzap* invocation

1. Resolve <wazzap-root> (repo root if in a git repo, else ~/Documents/wazzap/). Create directory if missing.
2. If a phase command and no slug= arg, read <wazzap-root>/_active. If missing or empty, this is a new decision — go to :up flow.
3. Read the matching sub-skill commands/<name>/SKILL.md and follow its checklist exactly.
4. On completion, update MANIFEST.yml per cross-cutting rules and tell the user the suggested next command.

Framework based on a "What's up / What's really up / Approaches / Let's go" leadership decision loop. The audit trail is the value: future-you should be able to read .wazzap/<slug>/ and reconstruct why past-you decided what you did.