Design Log

Design Log Skill

A generic "Stop & Think" protocol that combines research-driven design with Claude Code's plan mode. Research first, then code. One workflow, one approval gate, persistent documentation.

Credit: This skill extends Yoav Abrahami's Design-Log Methodology. The core principles (read-before-write, design-before-implement, Socratic Q&A, immutable history) are his. This skill adds Claude Code plan-mode integration, a mandatory research phase, hard gates, and a test-handoff phase.

How This Integrates With Plan Mode

• Plan mode handles codebase exploration (reading files, searching code, understanding architecture).
• Research phase handles domain knowledge gathering (books, articles, case studies) BEFORE codebase exploration.
• Design log handles persistent documentation and status tracking across sessions.
• They share a single approval gate via ExitPlanMode — no double-approval.

When This Triggers

Use this skill when the user explicitly invokes /design-log, asks for a design log, requests stop-and-think planning, or asks for documented design before a non-trivial feature, bug fix, refactor, workflow change, UI change, automation, or architecture decision.

Implicit use is appropriate only when the task clearly needs persistent design documentation before implementation. If the task is small and the user did not ask for /design-log, use the normal workflow instead.

When This Does Not Trigger

Not every task needs a design log. Skip for:

• Single-line fixes, typos, small tweaks.
• Tasks where the user gives very specific instructions with no ambiguity and does not explicitly invoke /design-log.
• Pure research or exploration questions.
• Routine implementation that is already covered by an existing [APPROVED] design log — extend the existing log instead.

For these, just do the work directly — no plan mode, no design log.

Required Inputs

Before writing the design log, identify:

• The project root and current branch/worktree state.
• The requested change and the user's success criteria.
• Relevant prior logs, unfinished logs, and prior research.
• The domain(s) that need research.
• The existing code paths, helpers, tests, docs, and architecture diagrams that may be reused.
• Whether implementation should continue after approval or stop at the approved plan.

If an input is missing, ask through AskUserQuestion unless existing logs, user instructions, or pre-scan findings already answer it.

Decision Gates

Stop and wait when:

• The user has not answered required Phase A questions.
• Research is incomplete.
• EnterPlanMode has not been called before Phase C exploration.
• The design log has not been saved with [DRAFT] status.
• ExitPlanMode approval has not been granted.
• The next action would merge to main, delete a branch, change secrets, or perform destructive/production-impacting operations.

Continue without another approval only after ExitPlanMode approval, and only for routine implementation decisions inside the approved plan.

Workflow (Protocol)

The protocol runs in five phases. Each phase summary below is enough to know what to do; the full step-by-step procedure for every phase lives in references/protocol-detail.md — load it when you actually enter the phase.

Phase A Is Non-Negotiable When User Invokes /design-log

If the user explicitly typed /design-log (or otherwise invoked this skill by name), Phase A clarifying questions are mandatory — "specific instructions" or "seems simple" are NOT valid reasons to skip. The user asked for the Stop & Think protocol; give them the Stop & Think protocol. Silently jumping to implementation is a protocol violation.

If you believe the task genuinely doesn't warrant Phase A, say so out loud before proceeding: "Skipping Phase A questions because [specific reason] — proceed or ask questions anyway?" and wait for the user.

Auto Mode Activates Only After Approval

If your environment uses an "Auto Mode" or similar fast-execution mode, it applies only to Phase D (Implementation) and Phase E (Test Handoff) — i.e., after ExitPlanMode approval.

During Phases A, B, and C (Discovery, Research, Explore & Document), Auto Mode is effectively suspended:

• Phase A: ask decision-shaping clarifying questions via AskUserQuestion; wait for answers.
• Phase B: do the research — do not skip because "the task seems simple".
• Phase C: exit plan mode and wait for user approval — do not self-approve and proceed.

Once the user approves via ExitPlanMode, Auto Mode resumes normally.

Phase A — Discovery

STOP. Do not implement anything. Steps: A0 Branch Setup → A1 Check Existing Logs → A2 Light Codebase Pre-Scan → A3 Ask Clarifying Questions via AskUserQuestion (usually 5+) → A4 Wait for answers. Full procedure in references/protocol-detail.md § Phase A.

Project-specific automation: If your repository documents a design-log number reservation script, worktree launcher, or branch naming convention, follow that workflow in A0. Otherwise, determine the next log number from .agent/design-logs/INDEX.md and existing filenames, then warn about possible collision in parallel sessions.

Phase B — Research

Mandatory. B1 Identify domain → B2 Read 3+ sources via an MCP web research tool (Tavily, Brave, Bright Data, or equivalent — NOT the built-in WebSearch/WebFetch) → B3 Extract principles, patterns, anti-patterns, deviations into Section 3 of the log. Time-box 5–10 min. Full procedure + research rules + domain table in references/protocol-detail.md § Phase B.

HARD GATE: If you delegated research to a sub-skill or sub-agent, you MUST wait for its result before calling EnterPlanMode. Do NOT enter Phase C while research is still running.

Phase C — Explore & Document

HARD GATE — READ BEFORE ANY TOOL CALL IN THIS PHASE: The FIRST tool call in Phase C must be EnterPlanMode. Do NOT run Glob/Grep/Read for codebase exploration, and do NOT call Write/Edit on the design log file, until plan mode is active. The design log file must be created INSIDE plan mode. Phase C ends with ExitPlanMode — a plain-text "approve to proceed?" message is NOT a substitute approval gate. If you catch yourself mid-exploration without having called EnterPlanMode, stop immediately, call it, and resume — do NOT rationalize continuing outside plan mode because "exploration already started."

Steps: enter plan mode → explore codebase + load architecture diagrams → create the design log file at .agent/design-logs/NNN-kebab-case-description.md from assets/design-log-template.md with status [DRAFT] → ExitPlanMode for the single approval. Full procedure in references/protocol-detail.md § Phase C.

Phase D — Implementation (After Approval Only)

Steps: status → [BEING IMPLEMENTED — DL-NNN] → build per Proposed Solution → update Implementation Notes on deviations → status → [IMPLEMENTED — NEED TESTING] → housekeeping (INDEX, status file, architecture diagrams, commit/push, deploy if applicable). Full housekeeping checklist (NO auto-merge, frontend release path, do-not-delete-branch, do-not-edit-after-merge) in references/protocol-detail.md § Phase D.

Phase E — Test Handoff

Collect unchecked Section 7 items → write to a project status file (e.g., current-status.md) under "Active TODOs" in the documented format → mark log [COMPLETED] only when all Section 7 items pass. Full procedure + format template in references/protocol-detail.md § Phase E.

Handling Mid-Implementation Feedback

Classify feedback (clarification / bug / missed constraint / scope expansion / refinement) and respond accordingly. Full table in references/protocol-detail.md § Handling Mid-Implementation Feedback. When uncertain: state your assumptions, propose options (quick fix vs. proper solution), ask for preference. Don't guess.

Output Format

The persistent artifact this skill produces is a design log file at .agent/design-logs/NNN-kebab-case-description.md, filled in from the canonical template at assets/design-log-template.md. Read that file when you need the structure; do not paste it into chat.

Sections in order: 1. Context & Problem · 2. User Requirements (Q&A) · 3. Research (Domain, Sources, Principles, Patterns, Anti-Patterns, Verdict) · 4. Codebase Analysis · 5. Constraints & Risks · 6. Proposed Solution · 7. Validation Plan · 8. Implementation Notes.

Status values ([DRAFT] / [APPROVED] / [BEING IMPLEMENTED — DL-NNN] / [IMPLEMENTED — NEED TESTING] / [COMPLETED] / [DEPRECATED]) and naming convention (NNN-description.md, sequential, lowercase-hyphens, English) are documented in references/protocol-detail.md.

Do not leave template placeholders such as [Question], [Key takeaway], or Test Case 1 in a real design log. Replace every placeholder with concrete project-specific content before calling ExitPlanMode.

Critical Rules

1. NEVER implement before approval — [DRAFT] means no coding.
2. ALWAYS ask clarifying questions first — understanding before action. If the user invoked /design-log explicitly, fast-execution modes do NOT override this. To skip, state the reason out loud and wait for confirmation.
3. ALWAYS research before designing — knowledge before architecture.
4. ONE approval gate — ExitPlanMode is the single approval for both plan and design log.
5. ALWAYS save a design log file — plan mode is ephemeral; the log persists.
6. ALWAYS update Implementation Notes — document deviations and which research principles were applied.
7. ALWAYS run Phase E — persist test items to your project status file and mark [COMPLETED] only once all tests pass.

Pre-Phase-A Check (when this skill is invoked)

This skill has disable-model-invocation: true (recommended) — it should not run automatically at session start. It runs only when the user types /design-log or otherwise invokes it by name. When invoked, before Phase A:

1. Scan .agent/design-logs/ for unfinished work.
2. Report any [APPROVED] logs not marked [COMPLETED].
3. Summarize last 3 logs for context.
4. Note domains already researched (for cumulative knowledge rule).

Gotchas

• Do not treat plan mode text as persistent documentation; always save the design log file.
• Do not let template placeholders survive into a real design log.
• Do not create a new log when an active related log should be extended; if creating a new one anyway, explain why.
• Do not use filename-only triage for prior logs; grep bodies and read related logs in full.
• Do not let Phase A's light pre-scan become full Phase C exploration before EnterPlanMode.
• Do not repeat old research verbatim; do targeted delta research and cite the prior log.
• Do not mark [COMPLETED] until every Section 7 validation item is checked off.

Adapting To Your Project

This skill is intentionally generic. To make it production-ready for a specific repo, you'll likely want to add:

• A design-log number reservation script (to prevent collisions across parallel sessions/worktrees).
• A close-design-log script (patches status in both the DL file and INDEX.md, runs any PII/secret guards, stages files).
• A git-ship workflow or skill (single entry point for commit/push/merge so the protocol is enforced).
• A subagent-driven-development skill for parallel task execution in Phase D.
• A references/research-sources.md file mapping domains → canonical books/articles for your stack.

See references/protocol-detail.md § "Project-Specific Hooks" for where to plug these in.

References

• references/protocol-detail.md — load when entering a phase and you need the full step-by-step procedure (Phase A0–A4, B1–B3, C, D housekeeping, E test handoff, mid-implementation feedback table, status values, naming convention).
• references/research-sources.md — load in Phase B (B2) when picking source recommendations and source tiers for the identified domain.

Assets

• assets/design-log-template.md — fill this out as the persistent design log file in Phase C; read it for the canonical Section 1–8 structure rather than reproducing it inline.

Evaluation Checklist

Self-check after the skill runs. If any answer is "no" you skipped a phase:

• Phase A: Asked decision-shaping clarifying questions via AskUserQuestion (not plain text), usually 5+ unless prior context answered enough, and waited for answers?
• Phase A: Read INDEX.md + relevant domain folders, grepped log bodies for keywords, surfaced findings before asking questions?
• Phase A: Codebase pre-scan done — existing solutions/reuse opportunities surfaced?
• Phase B: 3+ research sources cited via an MCP research tool (NOT WebSearch/WebFetch); time-boxed to 5–10 min?
• Phase C: First tool call was EnterPlanMode — no Glob/Grep/Read/Write happened before plan mode was active?
• Phase C: Design log file written using the template at assets/design-log-template.md, status [DRAFT]?
• Phase C: Exited via ExitPlanMode (the single approval gate) — not a plain-text "approve?" prompt?
• Phase D: Status moved through [BEING IMPLEMENTED] → [IMPLEMENTED — NEED TESTING]; INDEX and status file updated; git operations done via your project's documented workflow (not raw git push to main)?
• Phase E: All unchecked Section 7 items copied to project status file under "Active TODOs"; log marked [COMPLETED] only after all tests pass?