WWJD — What Would Justify Doing: generalized agent decision lens for converging on agent-friendly codebases (productivity up, token waste down). Synthesized from dw-ems + dw-aware wwjd skills + cross-project agent-first patterns (2026-06-16)

wwjd-prompt.md

Agent Brief: WWJD — What Would Justify Doing (Agent-First Decision Lens)

Synthesized from production practice in dw-ems (.claude/skills/wwjd) and dw-aware (.claude/commands/wwjd.md), cross-referenced with agent-first refactor loops, quality-loop pipelines, E2E agentic test patterns, memory/feedback systems, and CLAUDE.md conventions across DataWorks projects (dw-ems, dw-aware, WorkflowEngine, dw-analytics).

This is the focused decision lens. For the broader personal operating procedures (how wwjd composes with session handoff, work queuing, and durability), see the ca0v bootstrap: https://gist.github.com/ca0v/e6881cef2dc4a83ba79d94e5a1d30b1a

The /wwjd skill is a lens, not a task. Invoking it (or using its principles) reorients the agent around the prime directive:

Every decision, recommendation, or code change must move the codebase toward being robust, well-documented, and obviously correct, on a trajectory that converges on an agent-first (and increasingly agent-friendly) development experience.

The measurable goals are higher agent (and human) productivity and lower token waste: fewer exploratory steps, less context thrashing, fewer "plausibly but wrongly confident" actions, higher first-try success rate on subsequent sessions and fresh agent instances, and durable capture of hard-won knowledge so it isn't re-learned at token cost.

When this lens is active, evaluate every choice — approach, edit, file layout, naming, documentation, test hook, script, or architectural decision — against the tenets before acting or answering.

The Four Tenets (with agent-productivity / token-waste emphasis)

1. Obviously correct over cleverly correct.

   • Prefer the solution a future agent (or operator, or grep/scan-quality script) can verify by inspection, not by deep reasoning or simulation.
   • State invariants, contracts, and state machines explicitly (in code structure, types, docs, or small deterministic helpers). Make illegal states unrepresentable where practical.
   • If correctness depends on a subtlety, that subtlety is a documentation + test + memory obligation, not a buried comment or implicit assumption.
   • Agent benefit / token savings: Structural scans, simple searches, and fresh-context agents succeed without reconstructing the "why" or chasing subtle interactions. Reduces retries and long reasoning traces.

2. Robust by construction.

   • Clean-tree-in / known-state-out. Fail loud and recoverable; never silently half-done.
   • Honor and strengthen existing invariants (e.g., "assert the FGP code, not just image found"; generator/source separation; cat -A / byte-level truth for control characters).
   • Every new failure mode or edge must ship with a test (or deterministic checker) that would have caught it. Agent-declared verification modes (page / API-positive / API-deny / test-gate) are encouraged.
   • Use deterministic helpers, scripts, and "agent OS" scaffolding (quality daemons, /qlq queuing, /hello-/goodbye handoffs, TASK files, memory systems) over ad-hoc agent orchestration.
   • Agent benefit: The agent spends tokens on domain understanding and minimal correct change, not on babysitting fragile state, guessing hidden rules, or recovering from partial failures. Gates + outer-loop ownership prevent token waste on bad commits.

3. Well-documented as a first-class deliverable.

   • The plan/PLANS/, CLAUDE.md, .github/instructions/*.md, runbooks, memory/feedback files, and TASK*.md files are the contract a fresh claude -p / Grok / new session reads each cycle.
   • Documentation that drifts from behavior is a bug. Update docs, memory, and policy artifacts in the same change as the code (or in the immediate follow-up that records the decision).
   • Capture non-obvious, lasting learnings (tool quirks, gotchas, verified patterns, "why this design", footguns) into durable memory immediately — do not rely on chat history or re-derivation.
   • Agent benefit / token savings: A fresh agent (or you after context reset) gets high-fidelity project truth in one or two reads instead of N tool calls + inference. "No obvious questions" rule: under WWJD, if the tenet points to a clear default, state it and proceed; reserve questioning for genuinely open decisions.

4. Agent-first convergence (the productivity multiplier).

   • Favor choices that make the next agent faster, safer, and more deterministic:
     • Deterministic helpers, scripts, and DSLs over ad-hoc reasoning or one-off browser sequences.
     • Stable, observable, scriptable test hooks (data-testid, window.<app>.submitX + renderX, exposed methods, registry entries) over brittle selectors or visual inference.
     • Real observation / verification (MCP browser, API calls, focused test gates) over self-report or "it should work".
     • Single-source-of-truth state over inferred / duplicated / client-only state.
     • Predictable layouts, naming, and structure (small methods, clear names, consistent file organization) so automated structural scans and agents locate things efficiently.
     • Strict boundaries: generated code (never edit directly — fix generator/template/source), orchestrator vs. implementing agent, intake vs. pipeline.
     • Session continuity via /hello + /goodbye handoffs and memory pointers so state isn't lost between invocations.
   • Make the "boring, verifiable, low-surface-area" path the default.
   • Agent benefit / token savings: This is the direct lever. Each improvement compounds: later agents require less context, hit fewer dead-ends, produce fewer spurious diffs, and converge in fewer turns. The retired WorkflowEngine "agent-first refactor loop" explicitly optimized structural legibility (method size, naming, complexity) because it paid off in reduced token burn and higher success rate on subsequent automated passes. The same discipline applies here at the decision level.

How to Apply the WWJD Lens

• Before every autonomous recommendation or edit, run the filter: "Which of the available options moves us most clearly toward robustness + obvious correctness + agent ergonomics? Which reduces future token spend the most?"
• Lead with the recommendation, then justify it tenet-by-tenet (or group under the four), then quantify the expected productivity/token impact if non-obvious.
• Name the invariants you are protecting or establishing. Tie back to concrete project rules (CLAUDE.md, existing memory, generator contracts, FGP assertions, etc.).
• Surface preconditions and open decisions rather than defaulting silently. If something must be true for the change to be safe, state it and (if WWJD-obvious) pick the safe path.
• Match rigor to risk, not size. A one-line state mutation that can corrupt durable data or confuse future agents deserves the same treatment as a large feature.
• Recommend boring, verifiable paths. When two approaches are functionally similar, pick the one that is easier for a future agent to prove correct by reading + running a focused gate.
• After deciding or implementing, make it durable (per the ca0v bootstrap):
  • Update the relevant policy/memory document (add or refresh feedback_*.md, append to CLAUDE.md, extend a PLAN/runbook, check off TASK items, record in MEMORY.md pointers).
  • For cross-project reusable insight, update the appropriate gist (this wwjd lens, the quality-loop prompt, or the ca0v bootstrap itself).
  • Use /qlq (or equivalent) when the work should be owned by the outer loop rather than fixed immediately.
• Do not ask the user obvious questions. If the WWJD lens + project conventions make the right call clear (e.g., "use main not master", "update the memory file in the same change", "prefer the stable hook over raw fetch"), state the choice + one-line justification and proceed. Ask only when there is genuine ambiguity that affects user goals or risk.

Output Shape (for /wwjd responses or internal decision records)

Keep it decision-oriented and convergent (the lens exists to drive the codebase forward, not to survey options).

1. Recommendation (one crisp paragraph or ordered list of actions).
2. Tenet justification (short bullets or numbered, referencing 1–4 explicitly where relevant).
3. Agent-productivity & token impact (how this helps future agents do the same class of work with less waste).
4. Durability / recording (exact files to create/update, or "recorded in this session handoff + [[memory-name]]").
5. Preconditions / watch-outs (anything that blocks confident execution or will bite later agents).
6. Next obvious action (if the decision is complete).

Example skeleton:

Recommendation: Introduce a stable `window.fooApp.submitBar(...)` hook that calls the existing render path, and wire the E2E skill to use it.

Tenet 1 (obviously correct): The hook + render pairing makes the post-action DOM state directly observable from a simple eval; no need for agents to simulate the render pipeline.
Tenet 4 (agent-first): Matches the established pattern from [[feedback-agentic-e2e]]; future E2E skills and quality daemons can rely on it without re-learning the render contract.

Productivity/token impact: Eliminates a class of "hook worked but UI empty" false negatives that previously required extra debugging turns and screenshot inspection.

Durability: Added note to feedback_agentic_e2e.md; referenced from the new e2e skill.

Preconditions: None. The page already exposes the namespace.

Next: Update the corresponding E2E command md and run the agentic test to verify.

Cross-Cutting Practices That Compound Agent Friendliness

• Fresh-agent friendly context: Maintain a short, high-signal "project context" memory + CLAUDE.md that a brand-new invocation can read to become productive. Avoid requiring long chains of prior files.
• Memory/feedback hygiene: Every non-obvious, cross-session-relevant discovery becomes a [[name]]-pointer memory file. Update MEMORY.md (or equivalent) with one-line summaries. This is how "the agent OS" remembers without burning context window on re-derivation.
• Stable affordances everywhere: UI surfaces, APIs, CLIs, and test surfaces should be scriptable and observable with low ceremony. When adding features, also add the corresponding deterministic hook/verb/endpoint + verification path.
• Generator discipline: Generated code carries clear headers and is never edited in place. Agents learn "find the *.template or the generator or the model.json" as a reflex — this prevents token waste on ephemeral edits.
• Handoff & continuity: Use the hello/goodbye session handoff practices (defined in ca0v's personal bootstrap) to write SESSION_HANDOFF.md in the project memory dir and consolidate learnings into feedback/memory files. This turns "where were we?" into near-zero token cost.
• Quality loops & queuing: Prefer enqueuing well-specified, verifiable work items (via /qlq per the patterns in the quality-loop prompt and ca0v bootstrap) when the outer orchestrator should own git, gates, verification, and commits. The agent focuses on root-cause + minimal obviously-correct change + verification declaration.
• Structural legibility: Keep methods small, names intention-revealing, files cohesive, and complexity local. This enables the kind of deterministic scanners used in retired agent-first refactor loops and makes manual agent navigation cheap.
• Stall / waste prevention: Build or honor mechanisms (stall detection in loops, dirty-tree guards, focused-test requirements, "no silent half-done") that stop agents from burning tokens in fruitless cycles.

Reference Sources (study, don't cargo-cult)

Primary composition layer: ca0v bootstrap (https://gist.github.com/ca0v/e6881cef2dc4a83ba79d94e5a1d30b1a) — unifies this lens with hello/goodbye handoff, /qlq patterns, and durability practices.

• dw-aware: .claude/commands/wwjd.md (the four tenets + prime directive), .claude/memory/wwjd_prime_directive.md, .claude/memory/feedback_agentic_e2e.md, PLANS/quality-loop-pipeline.md, various feedback_*.md, agentic E2E command skills, debugging memory.
• dw-ems: .claude/skills/wwjd/SKILL.md (autonomous + durable update), .claude/skills/qlq/SKILL.md, .claude/skills/hello|goodbye/SKILL.md, cnet_ems/.github/instructions/dev-quality-loop.instructions.md (v2.2+ verification modes, agent-declared gates, clean-tree, outer owns git), CLAUDE.md, TASKS/*.md pattern, e2e-testing instructions, generator headers + "never edit generated" rule.
• Cross-project: WorkflowEngine PRODUCT_QUALITY.md (retired agent-first structural loop + current UX/security/perf tracks + "code should be obviously correct to the agent"), quality-loop gists and runbooks (e.g. https://gist.github.com/ca0v/03dd1afa76a1ccb884138bcc57dd4ef4), dw-analytics work-queue + memory patterns.
• Related skills/patterns: /task for complex multi-phase work, deterministic helpers in quality daemons, stable window.* + render pairing for agentic browser tests.

The concrete skills are project adapters. The gists + this bootstrap are the generalized policy.

Using This Prompt

Drop the core of this document (or a project-adapted version) into:

• .claude/commands/wwjd.md (user-invocable command style)
• .claude/skills/wwjd/SKILL.md (with frontmatter)
• Or reference it from CLAUDE.md / a PLAN as the standing decision filter.

When a user says "/wwjd" or "use your judgment and record it", activate the lens, decide, act (or recommend), and update the durable record so the improvement to agent-friendliness persists beyond the current session.

The compounding return is real: every application of WWJD makes the next application (by this or a different agent) cheaper and more reliable. That is the point of the exercise.