# Mine Sketch > Use when the user says: "sketch this out", "sketch this feature", "lightweight plan", "quick design and tasks", or wants structured planning without full caliper ceremony. Produces a lightweight design.md + task files for mine-orchestrate. - Skill: `nodejsmith/mine-sketch` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add nodejsmith/mine-sketch` - Raw SKILL.md: https://api.skillmd.com/api/skills/nodejsmith/mine-sketch/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Productivity - Author: NodeJSmith (https://skillmd.com/u/nodejsmith) - Updated: 2026-09-10 - Page: https://skillmd.com/skills/nodejsmith/mine-sketch --- # Sketch Lightweight structured planning — produces a design.md with FRs/ACs and task files for mine-orchestrate, without the full ceremony of mine-define + mine-plan. For tasks that need structure but not rigor: multiple files, real design decisions, well-understood territory. ## Arguments $ARGUMENTS — a description of what to build, or a feature directory path. Can be: - A feature idea: `/mine-sketch "add webhook support to notifications"` - A feature directory path: `/mine-sketch design/specs/005-webhooks/` (resumes existing sketch) - Empty: ask the user what they want to build --- ## Phase 1: Understand & Scope If $ARGUMENTS is empty, ask: > What would you like to build or change? If $ARGUMENTS does not point to an existing spec directory, paraphrase the request in one sentence to confirm understanding. ### Initialize CFL tracking Derive a `` from the request (kebab-case, max 40 chars). If $ARGUMENTS pointed to an existing spec directory, extract its number: ```bash cfl spec status --spec ``` If that succeeds, use the existing spec. If it errors with `spec_not_found`, tell the user the directory predates cfl tracking and proceed without it (skip all `cfl` calls for the rest of this run). Otherwise, create a new spec: ```bash cfl spec init ``` Record `dir` as the feature directory and `number` as ``. ### Start run Skip this section if cfl tracking was disabled above (no `` set). ```bash cfl run status --spec ``` - If the output has `"exists": true` — an active run exists. Record the `run_id` and continue (no new run needed). - If the output has `"exists": false` — try resuming a stopped run: ```bash cfl run resume --spec ``` If this succeeds, the stopped run is now active. If it errors with `no_stopped_run`, create a new run: ```bash cfl run start --phase sketch --base-commit $(git rev-parse --short HEAD) --spec cfl event sketch.started --spec ``` ### Check for resume If $ARGUMENTS pointed to an existing spec directory, check that directory for `design.md` — if present and has `**Mode:** sketch`, this is a resume. Read it before skipping Phase 2. If the feature owns resumable work state across invocations but the design lacks `## Operational Lifecycle` or any required lifecycle decision, run Phase 2's mandatory lifecycle clarification and update the design first. Otherwise skip directly to Phase 3 (task breakdown); `` and `run_id` are already set from the sections above, so `cfl` calls in Phases 3-5 work normally. Skip the rest of Phase 1 and all remaining Phase 2 work. Otherwise, continue to the codebase scan below. ### Quick codebase scan Read 3-8 files relevant to the change. Focus on: - Files that will be modified (understand current structure) - Adjacent files that establish conventions - Test files that cover the area This replaces the full researcher dispatch. Keep it fast — you're looking for conventions and constraints, not doing deep investigation. ### Escalation check If the scan reveals more than expected, stop and ask before designing. Concrete signals: - The change touches more services/packages than the request implied (cross-system dependencies you didn't expect). - It requires modifying a shared or foundational module with many callers. - It surfaces an architectural question with no single obvious answer (unclear interfaces, competing approaches). If any apply: ``` AskUserQuestion: question: "The codebase scan found more complexity than expected — . How should we proceed?" header: "Escalate?" multiSelect: false options: - label: "Upgrade to full caliper" description: "Stop here — invoke /mine-define for a full investigation and design" - label: "Continue with sketch" description: "Proceed with the lighter sketch despite the finding" ``` On "Upgrade to full caliper": tell the user to invoke `/mine-define` and stop. On "Continue with sketch": proceed to Phase 2 as normal. --- ## Phase 2: Design ### Clarify (if needed) Ask 1-2 questions **only** if something is genuinely uncertain and would change the design. Skip if the approach is obvious from the codebase scan. One clarification is mandatory when the change owns resumable work state across invocations. Propose and confirm: completion, retry eligibility and bounds, user-action recovery or deliberately terminal states, repeated-run convergence, visible accounting, and a realistic local validation scenario. If those decisions cannot stay lightweight, upgrade to `/mine-define` rather than guessing. ### Write design.md Read `${CLAUDE_CONFIG_DIR:-~/.claude}/skills/mine-sketch/design-template.md` and use it as the template. Populate from the codebase scan and the user's request. Be specific — reference actual file paths and patterns found. Skip if cfl tracking was disabled in Phase 1 (no `` set): ```bash cfl event sketch.design-written --spec ``` --- ## Phase 3: Task Breakdown ### Write context.md Write `/tasks/context.md`: ```markdown # Context: ## Problem & Motivation ## Key Decisions ## Constraints ``` ### Write task files Write each task to `/tasks/T{NN}-{slug}.md` using this format: ```markdown --- task_id: "T01" title: "" status: "planned" depends_on: [] implements: ["FR#1", "AC#1"] --- ## Target Files - create: `path/to/new_file.py` - modify: `path/to/existing.py` ## Prompt ## Verify - [ ] FR#1: - [ ] AC#1: ``` ### Task file rules - **Minimum tasks: 1.** Let the work's complexity determine the count. Single-task sketches are fine for focused changes. - **Every FR and AC** from the design doc must appear in at least one task's `implements` field and have a corresponding Verify criterion. - **Operational lifecycle verification**: When the design contains `## Operational Lifecycle`, responsible tasks must verify repeated failure, bounded retry/termination, user-action recovery or deliberately terminal behavior, and visible population accounting through assembled repeated-run tests. Isolated status-transition tests are insufficient. - **Target Files are required** — they drive the orchestrator's scope boundaries and reviewer injection. - **Prompt must be self-contained** — a fresh subagent with only context.md and the task file must be able to execute it. - **Task ordering**: foundational types before consumers. No task may depend on outputs from a higher-numbered task. Skip if cfl tracking was disabled in Phase 1 (no `` set): ```bash cfl event sketch.tasks-written --spec ``` --- ## Phase 4: Comb Run the fine-toothed comb on the design doc and task files together. Skip the cfl dispatch/gate calls below if cfl tracking was disabled in Phase 1 (no `` set). The comb itself still runs regardless. ```bash cfl dispatch sketch-comb --agent-type fine-toothed-comb --spec ``` Record the `dispatch_id`. ``` Agent: subagent_type: fine-toothed-comb prompt: | Read this design file and its task files: - Design: - Tasks: /tasks/ Go over them with a fine-toothed comb. Check: - Design and tasks are consistent (no contradictions, no drift) - Every FR/AC is covered by at least one task's implements + Verify - When Operational Lifecycle is present, tasks verify assembled repeated-run behavior, retry bounds/termination, recovery or deliberately terminal states, and visible accounting - Target Files are complete (no file referenced in Prompt but missing from Target Files) - Prompts are self-contained (no "as discussed" or assumed context) Define blocking as: a direct inconsistency, missing coverage, or an error that would mislead execution. A section that could be more detailed is minor, not blocking. ``` After the comb completes: ```bash cfl dispatch end cfl gate sketch-comb --verdict --spec --data '{"blocking": , "minor": }' ``` Verdict: `blocking` = 0 → PASS, `blocking` > 0 → FAIL. Read `${CLAUDE_CONFIG_DIR:-~/.claude}/skills/mine-comb/comb-gate.md` and apply it with: - **`
`**: `Sketch comb` - **`minor_blocks`**: `false` - **``**: fix the findings in the design doc and/or task files, then re-run this phase --- ## Phase 4.5: Challenge Run the mandatory sketch-time challenge. Read `${CLAUDE_CONFIG_DIR:-~/.claude}/skills/mine-challenge/challenge-gate.md` and follow it with: - **`
`**: `Challenge` - **``**: `sketch-challenge` - **``**: `` - **``**: `--critics=2` - **``**: (empty — first challenge in this run) - **``**: If any finding was applied to `design.md` (`disposition: applied` with `design-level: Yes`, including a TENSION finding's chosen side), re-run Phase 4 (the comb) against the now-edited design doc and task files together, then return to this point — do not re-run the challenge. Then, if any CRITICAL finding was produced (check the findings file), offer the upgrade-to-caliper choice before proceeding to Phase 5. See below. Skip the cfl dispatch/gate/finding calls if cfl tracking was disabled in Phase 1 (no `` set). The challenge itself still runs regardless. Skip this resume check too if cfl tracking was disabled in Phase 1 (no ``/`run_id` set) — the challenge itself still runs unconditionally in that case, same as a first run. Otherwise: if this is a resume and the challenge already ran in a prior session, skip this phase. Check via: `cfl event list --event challenge.findings-persisted --run ` — if any row's data contains `"gate_type": "sketch-challenge"`, the challenge already ran and its findings were persisted for this run. Do not use `review.gated` for this check — that event fires when the gate is recorded (`challenge-gate.md` step 4), which happens *before* findings are persisted and resolved (steps 5–6); a run interrupted between those steps would otherwise look "already ran" on resume and skip re-persisting its findings. `challenge.findings-persisted` fires only after persistence *and* `` (the comb re-run and upgrade-to-caliper offer) complete (`challenge-gate.md` step 8) — a run interrupted before then re-enters the whole phase on resume rather than skipping ``'s work. ### Re-comb after design-doc edits If Phase 4.5 resolution edited `design.md`, re-running Phase 4 catches inconsistency the edit may have introduced between the doc and the task files — the same reasoning `mine-define`'s Phase 5.5 applies to its own comb. Skip this step entirely if no finding touched `design.md`. ### CRITICAL escalation If any CRITICAL finding was produced by the challenge (regardless of its disposition — even if applied), present the gate below. This is a major gate (challenge finding walkthrough, see `interaction.md`) — run `context-pct` and prepend the result to the question: ``` AskUserQuestion: question: "[Context: N%] The challenge found a CRITICAL structural issue. A sketch may not be the right vehicle for this change. Upgrade to the full caliper workflow?" header: "Escalate?" multiSelect: false options: - label: "Upgrade to full caliper" description: "Stop here — invoke /mine-define for a full investigation and design" - label: "Continue with sketch" description: "Proceed with the sketch despite the CRITICAL finding" ``` On "Upgrade to full caliper": tell the user to invoke `/mine-define` and stop. The resolved findings have already improved `design.md`, which `/mine-define` picks up. On "Continue with sketch": proceed to Phase 5 (Handoff) as normal. Phase 5 does not begin until the challenge (and any escalation prompt) completes. --- ## Phase 5: Handoff Present the design doc and task file paths to the user, then ask. This is a completion gate (see `interaction.md`) — run `context-pct` and prepend the result to the question: ``` AskUserQuestion: question: "[Context: N%] Sketch complete — design.md and task files are ready. What next?" header: "Handoff" multiSelect: false options: - label: "Execute via /mine-orchestrate" description: "Advance to orchestrate phase — run tasks with full execution gates" - label: "Revise — I have changes" description: "Tell me what to change" - label: "Save and stop" description: "Keep the sketch on disk; pick it up later" ``` ### On "Execute" Skip if cfl tracking was disabled in Phase 1 (no `` set): ```bash cfl event sketch.approved --spec ``` Update design.md `**Status:**` from `draft` to `approved`. Invoke `/mine-orchestrate ` directly — auto-continue, don't stop for the user. mine-orchestrate's resume-protocol handles the phase advance to `orchestrate` internally (with correct `--base-commit`, `--tmpdir` resolution). Do NOT call `cfl run advance-phase` here. ### On "Revise" Ask what to change. Apply edits to design and/or tasks. Re-run Phase 4 (Comb). Present the handoff gate again. ### On "Save and stop" Confirm: "Sketch saved at ``. Resume with `/mine-sketch ` later."