Deepthink — Structured Planning Methodology

Use when a task is too complex or open-ended for a single-pass /plan. Deepthink runs user clarification, parallel exploration, compares design lenses, passes through a skeptic gate, scores itself on 7 quality dimensions, and closes with a retrospective.

When /plan is a focused sprint, deepthink is the reconnaissance, strategy, and mobilization phase before the sprint begins.

The 4-Pattern Planning Scale

Planning tasks come in 4 shapes, lightest to heaviest. Pick the lightest pattern that fits; escalate only when the lighter one proves insufficient.

Decision rule:

1. Is the design space OPEN or CLOSED?
   • CLOSED → /plan
   • OPEN → continue
2. For OPEN — is the decision small (1-2 turns) or big (plan file)?
   • SMALL → /pulse
   • BIG → continue
3. For BIG open design — is it multi-domain, multi-worker, fuzzy goal, or >1 day?
   • YES → /deepthink (full)
   • NO → /shape

If a user explicitly invokes "deepthink" but the task fits /plan scope, surface the choice before proceeding — see "Trigger discipline" in Pitfalls below for the exact wording and rationale.

When to Use

If the user invokes "deepthink" but the task clearly fits the /plan column on 4+ of 6 axes, do not silently run the full 9-phase process — see "Trigger discipline" in Pitfalls below.

The full 9-phase deepthink produces a ~30KB packet and 3 parallel workers, which is overkill for a 1-2 turn question. /pulse is the standalone sibling skill for that case — see its SKILL.md for the protocol. If a /pulse answer reveals the task is bigger than expected, escalate to the full 9-phase deepthink in a follow-up turn.

For multi-step design tasks that need a plan file deliverable (but not the full 9-phase), see the sibling /shape skill. /pulse is inline analysis with no plan file; /shape is the multi-step sibling that produces a plan file via /plan + multi-model-review huddle composition.

Core Workflow

Phase 0: CLARIFY — User Interview
Phase 1: INVENTORY — Capability Reconnaissance
Phase 2: EXPAND — Parallel Exploration (3 workers)
Phase 3: LENSES — Design Alternatives (3 lenses)
Phase 4: SYNTHESIS — Unified Plan
Phase 5: SKEPTIC — Adversarial Review
Phase 6: DISPATCH — Kanban / Worker Execution
Phase 7: VERIFY — Acceptance Close
Phase 8: RETROSPECTIVE — Feedback Loop

Phase 0: CLARIFY — User Interview & Scoping

Before ANY exploration begins, interview the user. A plan built on assumptions is worse than no plan.

Ask until you can answer:

• Goal: One-sentence purpose?
• Success criteria: How will we know it's done?
• Non-goals: What are we NOT doing?
• Constraints: Budget, timeline, tech stack, platform?
• Existing work: What already exists?
• Users: Who uses this? Tolerance for bugs?
• Risk tolerance: Experiment or production?
• Decision makers: Who decides trade-offs?
• Output format: Kanban dispatch, document, handoff?

Infra boundaries (added 2026-06-10, post-mortem on a 25-decision leak): can this run introduce new services, new resources, or new deploy steps? Strict no-new-infra is a real constraint — say so. The default in most runs should be "ask before introducing infra, even if it's the cleanest design." This is the most common source of implicit decisions that never get surfaced.

Open product decisions (added 2026-06-10): are there open questions in the living plan / existing plan-of-record that this run should resolve, or are they explicitly out of scope? If there are open Qs (e.g. "Q2: voice = fine-tune vs prompt"), the worker should NOT close them by default — surface them as NEEDS USER even if a defensible default exists. Closing open Qs via worker defaults is a process smell.

Consent / privacy surface (added 2026-06-10): does this work touch a consent-sensitive surface (per-person profiles from public data, public leaderboards, recognisable fingerprints in published artifacts)? If yes, the mitigations are mandatory before any public surface ships — surface them in Phase 0, not after.

Reversibility (added 2026-06-10): what's cheap to reverse (a config flag) vs expensive (a new infra resource, a public artifact, a published post)? Mark the boundary explicitly. Workers will default to "build the cleanest version" if you don't tell them reversibility matters.

Scope-creep boundary (added 2026-06-10): what's the explicit list of things this run is NOT touching? Workers will be tempted to "while we're here" — give them a fence.

Exit: All questions answered or flagged NEEDS USER. User confirmed scope.

Phase 1: Capability Inventory

Take stock of available tools, skills, and assets before exploring the problem.

• List live Hermes skills (skills_list() or find ~/.hermes -name SKILL.md)
• Tag as custom vs bundled (check author in frontmatter)
• Check backup status against skill repos
• Present as flat per-item list (one skill + repo per line)

Phase 2: Parallel Exploration

Spawn 3 independent workers via delegate_task:

Worker A — Architecture & Implementation
  - Map codebase, entrypoints, control flow
  - Identify gaps between current state and goal

Worker B — Risk & Dependencies
  - Tests, CI, package metadata
  - Security, privacy, operational risks

Worker C — Goal & Constraints
  - Extract actual goal, intended users, constraints
  - Find open product decisions

Phase 3: Design Lenses

Generate roadmap drafts through 3 competing lenses:

Lens A — MVP First: smallest useful path, cut ideal design
Lens B — Robust First: defensive architecture, testing, audit
Lens C — Product/Ops First: deployment, monitoring, onboarding

Phase 4: Synthesis

Merge all 6 outputs into one authoritative plan:

1. Context & goal
2. Current verified state
3. Guiding decisions (NEEDS USER if unresolved)
4. Phased roadmap (goal, files, exit criteria, verification, effort, worker lane)
5. Architecture diagram (ASCII if useful)
6. Open decisions
7. Verification strategy
8. Risks & sequencing
9. Changelog

Save as .deepthink/ artifact packet:

spec.md         — problem, goal, non-goals, constraints, success criteria
plan.md         — phased roadmap with file paths and verification
tasks.md        — Kanban-ready task breakdown
acceptance.md   — acceptance criteria and test plan
handoff.md      — executor briefing

Phase 5: Skeptic Pass

Review the plan before any execution. Use structured checklists covering:

• Spec — Is the problem real? Are success criteria testable?
• Plan — Are phases independent? Exit criteria concrete?
• Tasks — Are tasks atomic? File paths exact?
• Acceptance — Is each criterion binary? Verification concrete?
• Holistic — Narrative consistency? YAGNI? Bus factor?
• Mechanical cross-check — grep all cited line numbers, re-measure every "Measured constraints" file size, confirm function signatures, version pins, and branch refs. Versioned plans (v(N) → v(N+1)) carry stale numbers forward; fix before declaring ready. See Operational Notes.

Score:

• GREEN (0-2 minor issues) → Proceed
• YELLOW (3-5 issues) → Fix then proceed
• RED (6+ or fundamental flaw) → Return to Synthesis

This GREEN/YELLOW/RED score is the gate: it decides whether Phase 6 starts now, after fixes, or not at all. The separate 7-dimension Quality Scorecard below is a different measurement — it doesn't gate progression, it's the quality report you hand the user once the gate has passed.

Phase 6: Dispatch to Execution

Convert the approved plan to Kanban cards:

t1 = kanban_create(title="phase-1: ...", assignee="<profile>", body="...")
t2 = kanban_create(title="phase-2: ...", assignee="<profile>", parents=[t1])

Each card carries the relevant section of the deepthink packet.

Phase 7: Verify & Close

1. Run verification commands from the plan
2. Check exit criteria for each phase
3. Update living plan — bump version, mark completed phases
4. Archive .deepthink/ packet or leave for next session

Phase 8: Retrospective

After execution, ask TWO questions:

1. What should we ADD? — missing coverage
2. What should we REMOVE? — checklist creep, skill bloat

Run via delegate_task or answer directly. Save as .deepthink/retrospective.md.

Every 5th retrospective, audit this skill itself. Delete unused checklist items, consolidate duplicative template sections, remove process steps that never triggered.

Pitfalls

These are the failure modes that have fired in real deepthink runs. Embed in the next run's process; don't re-derive.

Version discipline

If the user says "keep at v0.1.0 until 100% done" or any equivalent ("don't bump the version while building," "stay at the release version," "one version for the whole build"), DO NOT fragment the version number into 0.1.1, 0.2.0, etc. while building. Stay at the release-target version. Bump once at release. Version fragmentation in the middle of a build is a process smell, not a feature. The plan/packet/acceptance can use sub-labels internally (v0.1.0-Phase-1, v0.1.0-Phase-2), but the skill's version: field stays at the release target until the user explicitly bumps it.

Subagent model preference

delegate_task workers inherit the parent's active model by default. If the user has a stated preference for the work type (e.g., "free models only" with opencode/deepseek-v4-flash-free for coding), override with acp_command='opencode' + acp_args=['run', '--model', '<user-preferred>', '--acp', '--stdio']. Don't burn the user's preferred-model budget on the parent's paid model by default. Check the user's profile/memory for the preference before spawning; if no preference, ask once.

Cron-vs-daemon for "set and forget" capture

When the user wants "set and forget, automatic, every event" capture (transcripts, logs, metrics), prefer a one-shot script + cron + state file over a long-running daemon. Same effect, up-to-30s lag, no cross-platform daemon-management pain, automatic crash recovery via state file. Reference: productivity/transcript-archive/references/cron-vs-daemon.md.

Parent vs child session capture

When the user says "transcripts" or "always save the session," clarify: parent (the chat with the agent) or child (the workers the agent spawns). Different capture mechanisms. The parent often has NO native capture; the child usually does. Don't conflate them. Reference: productivity/transcript-archive SKILL.md "Parent vs child session distinction" section.

Workers' output can flood the parent

If the parallel exploration produces 50KB+ per worker, the parent's context will be dominated by 3 worker summaries. Mitigation: cap worker output to <20KB each in the task spec, OR post-process the outputs to a file and have the parent reference the file rather than inline the summary.

Skeptic pass finds real issues

The 5-checklist skeptic pass (Spec / Plan / Tasks / Acceptance / Holistic) is not ceremony. In one observed run, it found 2 minor gaps (AC-17 missing, v1 receipt engram_id placeholder) that would have shipped as bugs. Always run it. Always apply the patches.

Trigger discipline: when the user invokes "deepthink" by name

If the user explicitly invokes "deepthink" (e.g. "use deepthink on this", "deepthink this for me", "look at X with deepthink"), follow the recipe or surface the choice — never silently shortcut to /shape or /plan. The user picked the named skill for a reason.

Two options when invoked by name:

1. Run the full 9-phase deepthink (default)
2. Run the lighter /shape pattern (only if the task fits /plan scope on 4+ of 6 axes) — but ONLY after saying one sentence that names the choice: "You asked for deepthink; this task is borderline /plan. I'll run /shape and skip the ceremony that doesn't fit. Speak up if you want the full 9-phase."

The existing /pulse LITE paragraph and /shape sibling pointer above already state this rule. This pitfall exists because the rule fires in real sessions and gets bypassed. In one observed run, the agent silently ran /plan + a multi-model-review huddle for a task that fit /plan scope on 5/6 axes because the design was open. The user caught it: "did you use my authored deepthink skill for this?" The fix: surface, don't shortcut. If unsure, ask one sentence via clarify before proceeding. The skill is invoked by name → respect the invocation → either follow the recipe or name the alternative in plain chat.

User preference: when there's a design disagreement, prefer safer over cleverer

When a huddle surfaces a real disagreement between seats, the user has a consistent preference: pick the safer, more reversible option over the cleverer, more efficient one. Concrete pattern observed: one seat said "alert + sidecar, no auto-trim" (safer, human-judgment-preserving); another said "auto-trim from top" (cleverer, less data loss risk if you trust the heuristic). The user explicitly chose the safer path. When you see this kind of split, lean toward the option that:

• Preserves information (no auto-deletion, no auto-trim)
• Surfaces the decision to a human (alerts, logs, sidecars) rather than automating it
• Is reversible (can be undone)
• Fails visibly (exits non-zero, logs the failure) rather than silently

This is a standing user preference, not a one-time choice. The cleverer option might be right in some cases (e.g., when the user explicitly wants efficiency over safety), but the default is safer.

Quality Scorecard

Every deepthink plan is scored across 7 dimensions:

Score after Phase 5. Target: 32/35 minimum. Report the scorecard to the user.

Related Skills

• plan — Single-pass, for well-understood tasks
• skillopt — Optimize skills
• kanban-orchestrator — Task dispatch
• brainmap — Brain wiring audit

Operational Notes

Two recurring gotchas that bit a real session and are worth embedding in the next agent's mental model.

Pre-Finalize Mechanical Cross-Check

A plan is a promise. Every cited line number, file size, function signature, version pin, and branch ref is a contract with the executor. Versioned plans (v(N) → v(N+1)) routinely inherit stale numbers from the prior version, and the executor acts on the bad data without knowing it's stale.

Before declaring any non-trivial plan ready, run the mechanical checks. The plan's "Measured constraints" section is the highest-risk area: data files grow, indexes rebuild, file sizes drift. A 5-minute grep/du pass catches what an hour of design review misses.

Required checks:

• grep -n every line number cited in the plan. Confirm the line still contains the cited code. Mismatch = update the plan or fix the code.
• du -h every file cited in "Measured constraints". Mismatch = re-measure and update. (Real example: a v4 plan said 15 MB headroom; the actual file was 16 MB. The v5 plan would have shipped with a wrong number.)
• grep "def <name>" every called function. Confirm the signature hasn't drifted.
• --version or git log every version pin and branch ref. Resolve or update.
• Re-derive every "X is the highest-Y in the dataset" claim against the current data.

Rule: if a number, path, or line is in the plan, it must be re-verified within the same session.

Project-Convention Override

The default deepthink artifact is a .deepthink/ packet of 5 files (spec/plan/tasks/acceptance/handoff). Project conventions may override this — and usually should. A consistent set of in-repo plan files is more useful than a theoretically-pure 5-file packet that lives elsewhere.

Before saving the plan, check the project for an existing pattern:

• Does the project have a .hermes/plans/, .plans/, docs/plans/, or similar directory? Use it.
• What's the existing naming convention? YYYY-MM-DD_HHMMSS-topic.md (timestamped), v(N)-topic.md (versioned), or something else? Match it.
• Single file with all phases inline, or split into multiple? Match it.
• Does the existing plan format have a "For Hermes:" opening directive, a dependency graph, a measured-constraints block, etc.? Borrow the structure.

Match the project, not the skill default. The plan's value comes from being a useful artifact the next session will read — not from being theoretically-pure.

Pitfalls & Meta-Lessons (from real runs)

These emerged from actually running deepthink, not from the spec. Patch the skill with new ones as you find them. The "every 5th retrospective" rule in Phase 8 is the natural cleanup point.

Multi-line bash in chat output gets mangled — write to a file instead (added 2026-06-11)

When the deepthink (or any skill) produces multi-line bash for the user to copy-paste into a terminal, Hermes chat output mangles it: lines get prefixes (> , indentation, etc.), quotes get escaped, heredocs lose their EOF sentinels. The user pushed back: "hermes adds lines in front of every line which makes easy pastes impossible."

Fix: when producing multi-line bash the user needs to run:

1. Write the script to ~/temp/<descriptive-name>.sh (the user's scratch dir; survives reboots, easy to find)
2. Make it executable (chmod +x)
3. Reply with the path and a 1-line "preview" of what it'll do (so the user can sanity-check before running)
4. Never paste multi-line bash inline in chat for the user to copy

Quick test: if the bash output spans more than ~3 lines OR contains heredocs / nested quotes / backticks, write to a file. The user runs bash <scratch-dir>/<name>.sh directly.

Works in this profile because the user has ~/temp/ set up as their scratch convention. Other users with different conventions: substitute their preferred scratch path.

Subagent model selection — pin the model you actually want

delegate_task subagents inherit the parent's active model by default. If the user has a free-model preference (e.g. OpenCode free tier), the workers will burn the wrong model. To pin workers to a specific model, pass acp_command and acp_args:

delegate_task(
    goal=...,
    context=...,
    acp_command='opencode',
    acp_args=['run', '--model', 'opencode/deepseek-v4-flash-free', '--acp', '--stdio']
)

The default acp_command=None falls through to the Hermes-subagent transport and inherits the active model — which may be a paid-style model on a free-tier user. On a 3-worker run that produces 80K+ output tokens, this is the difference between a few cents and a real bill.

Lens collapse is allowed (and common)

The 3-lens design (MVP / Robust / Product-Ops) is an exploration tool, not a commitment device. For a 1-skill design where all 3 lenses point at the same artifact, they collapse into a 2-phase build (e.g., "lite for Day 1" + "full for Day 3"). Document the collapse explicitly in the synthesis so the user knows the lenses were considered.

When NOT to collapse: the lenses diverge meaningfully (one says "use library X", another says "build from scratch"). In that case, keep them separate and let the user pick.

Open product decisions need a closing step

Worker C's output usually includes "open product decisions" (OD-1 to OD-N). The synthesis phase MUST resolve them — don't leave them as TODOs in the spec. Resolution options, in order of preference:

1. Ask the user via clarify (if the decision is blocking)
2. Default to the worker's recommendation and record the assumption in the spec
3. Mark as NEEDS USER and ship anyway (if the default is sane)

A spec that says "OD-3: TBD" is a spec that will be re-litigated at every subsequent step.

Synthesis is the bottleneck

3 parallel workers producing 80KB+ total output is the easy part. Folding that into 5 packet files is the slow part. For the next deepthink iteration: build a synthesize sub-skill that takes N worker outputs + the deepthink templates and emits the packet directly. Until then, budget the synthesis at 2-3x the exploration time.

Bash arithmetic on grep -c output

grep -c emits a trailing newline. [[ "$VAR" -gt 0 ]] rejects "0\n" with a syntax error. The fix in any shell script that counts matches:

COUNT=$(grep -cE "PATTERN" file 2>/dev/null | tr -d '\n' || echo "0")
COUNT=${COUNT:-0}

Both tr -d '\n' and the ${VAR:-0} default are needed — the first strips the newline, the second handles the || echo "0" fallback case where grep returned non-zero.

Safety filter blocks cd into ~/.hermes/... paths

cd ~/.hermes/profiles/<profile>/skills/<x> triggers a write-protection filter. The shell will refuse the next command. Two unblock strategies:

1. Use absolute paths instead of cd:

   python3 ~/.hermes/profiles/<profile>/skills/<x>/scripts/foo.py

   This works from any cwd. The script doesn't need a cd first.
2. python3 -c "..." with embedded content is blocked more often than a direct script call. Write a script file and call it; don't inline.

Don't retry blocked commands — surface the specific command (or segment) that triggered the block, not a generic summary. The user profile and the deepthink workflow both expect this.

Markdown **bold** in heredocs renders as *** literally

When writing bash patterns inside a markdown heredoc or string, ** (markdown bold) can render as *** literally, which is invalid bash. Either escape it (\*\**) or use single-asterisk emphasis. The grep pattern in a $(...) block is the most common site for this bug.

Skeptic pass should run before build, not after

A 5-checklist skeptic pass with 2 minor patches took 5 minutes. The same issues caught at the implementation stage took 30+ minutes to fix-and-retest. Phase 5 is cheap insurance — don't skip it.

User confusion is a stop signal, not a re-explain-the-plan signal

If the user says "I'm confused", "explain what we're looking at", or "wait, what?", mid-plan, the right response is to back up to the picture — one short paragraph in plain language: what the corpus/project/thing actually is, what the next concrete step is, and what they're waiting on. NOT to keep adding detail, re-paste the plan, or re-issue a /pulse. The user is signaling that the accumulated planning-speak has lost them. Strip jargon, name the daily loop, name what's blocked, ask if that clears it up. Different from the "Primary deliverable drift" pitfall above: that one is about proactively re-anchoring to a named primary deliverable; this one is about a reactive signal that the user has lost the thread and needs a plain-language re-ground (often the original primary deliverable is no longer the right anchor — sometimes a fresh re-orientation is needed before re-anchoring works).

Multiple redirects in a single session = discovery problem, stop the loop

If the plan gets redirected 3+ times in one session, the discovery phase didn't go deep enough. Stop, ask ONE clarifying question (not the full Phase 0 interview), and re-ground. Patches to the same plan, week over week, are fine; redirecting three times in 30 minutes is a sign of a hidden constraint the user hasn't named. Default action after the third redirect: ask "is X the actual goal here, or is something else going on?" — surface the underlying intent.

Primary deliverable drift in long planning conversations

Long conversations drift from the original primary deliverable to adjacent side quests. Pattern: user names KB-1 (the knowledge base) as the primary; over several turns the conversation shifts to skills / monetization / strategy / what-if-questions; the agent ends up building 10 side-quest skills and the user has to call it out ("are you not focused on making a knowledgebase?"). The fix:

• Phase 0 (CLARIFY): name the primary deliverable in writing, put it at the top of the plan artifact.
• Phase 4 (SYNTHESIS): re-anchor. Check whether the synthesis still serves the primary deliverable or has drifted. If drift detected, surface it before the user does.
• Red flag: a directive like "build all this" in a long conversation may signal agreement-from-fatigue, not a real directive. Confirm the deliverable before building.

User redirects to a direction the synthesis didn't even offer

The huddle may converge on options A, B, C. The user picks D — something that wasn't on the menu, OR was on the menu and was rejected in the synthesis. This is a real and recurring pattern, not a "user changed their mind" failure. The right response:

• Don't argue for the synthesis's recommendation. The user is closer to the work than the huddle is.
• Don't re-run the synthesis to get D as an option. That burns 5-15 minutes for no gain.
• Don't ask "are you sure?" — that's paternalistic. The user has context you don't.
• Acknowledge the redirect briefly. One sentence: "OK, sharper direction" or "got it, switching to X."
• Update the plan artifact to reflect the new direction. New section, new Changelog entry, possibly new skill priority.
• Continue with the relevant phases. Skip Phase 0-5 unless the redirect genuinely changes the goal/constraints.
• Reuse the huddle output where it still applies. The "what's hard / what's risky" signals from the synthesis are usually still true even if the direction changed.

Real example (2026-06-10): the KB-direction huddle converged on "KB is premature, use corpus for case study + skill unblocks." The user then redirected to "OSS first responder" (pulse + ship daily loop) — a direction the huddle hadn't offered. I integrated the redirect by adding §Huddle review + §Redirect sections to the plan, logging in Changelog, and re-ordering skill priority. Did not re-run the synthesis. Did not re-ask. The new direction was sharper and made the case study + skill work downstream of it (rather than parallel).

The reverse also happens: the user redirects to a direction the huddle offered but rejected (e.g., B-narrow instead of D). Same handling — integrate, don't re-litigate. The huddle's job is to surface options; the user's job is to pick.

Changelog

• 2026-06-16 (pass 2, huddle-reviewed) — Reconciled the Phase 5 GREEN/YELLOW/RED gate against the separate 7-dimension Quality Scorecard (one gates progression, one is the post-gate quality report — now stated explicitly), collapsed the "explicit deepthink invocation" paragraph from 3 duplicate copies down to 1 (Trigger Discipline pitfall) with cross-references elsewhere, and removed personal-setup leaks (literal /home/argo/... paths genericized to ~/..., a specific huddle seat-name example genericized).
• 2026-06-16 (pass 1) — Aligned frontmatter with the other 3 planning skills (metadata.hermes.tags/related_skills instead of flat tags/trigger), fixed inconsistent phase-count references (9 phases, not 8) and the misattribution describing /pulse as living inside this skill, dropped a duplicated heading and a duplicated paragraph, and stopped stamping changelog entries with an internal "v3.0.x" label that never matched the frontmatter's version: 0.1.0 — dates are the changelog's version now; the version: field bumps once at release per the Version Discipline pitfall above.
• 2026-06-11 — Added "Multi-line bash in chat output gets mangled — write to a file instead" pitfall. Captures a 2026-06-11 user correction ("hermes adds lines in front of every line which makes easy pastes impossible"). The fix: write multi-line bash to ~/temp/<name>.sh, give the user the path. Inline pasting only works for ≤3 line commands.
• 2026-06-09 — Added "Pitfalls & Meta-Lessons" section from first real run. Captured 8 lessons: subagent model selection, lens collapse, OD closing step, synthesis bottleneck, bash grep -c arithmetic, safety filter cd blocking, markdown ** in heredocs, skeptic-pass timing.
• 2026-06-09 — Added "Operational Notes" section with two reusable patterns: (1) Pre-Finalize Mechanical Cross-Check — v(N) plans carry stale line numbers and file sizes forward; grep/du every cited value before declaring ready. (2) Project-Convention Override — match the project's existing plan directory, naming convention, and file structure rather than the default 5-file .deepthink/ packet. Also added a "Mechanical cross-check" item to the Phase 5 Skeptic checklist.
• 2026-06-09 — Created. Consolidates deep-plan (v2.1.0) and ultraplan (v2.0.0) into one skill named deepthink. Archives both predecessors.