| name | adhd-workflow |
| description | ADHD-friendly session and task workflow for craft users โ captures context at session end, restores it at session start, picks the next task, breaks through blockers, holds focus on one task, reviews a craft spec, or refines a vague craft prompt. Use when wrapping up or resuming a coding session, when deciding what to work on next (also "what's next", "pick a task for me", "give me something to do"), when stuck or in decision paralysis, when focusing on a single craft task, or when reviewing/refining a craft spec or prompt. The full intent-to-operation map is in the "When to Use" table below. |
ADHD Workflow Skill
Expert in ADHD-friendly session and task workflow for craft users. Reduces cognitive overhead at the points where ADHD costs the most: session boundaries (context loss), task selection (decision paralysis), being stuck (overwhelm), and unclear prompts (rework cost).
When to Use
Activate this skill when the user's prompt matches any of these concerns:
| User intent | Operation |
|---|
| "I'm done", "wrap up", "end session", "save progress" | Session completion |
| "where did I leave off", "what's the state", "recap me" | Context restoration |
| "what next", "what's next", "what should I work on", "I can't decide", "pick a task for me", "give me something to do", "what should I do now" | Next-task suggestion |
| "let me focus", "single task", "Pomodoro" | Focus mode |
| "I'm stuck", "I don't know what to do", "blocked" | Unblock helper |
| "review my spec", "approve spec", "archive spec" | Spec review |
| "fix my prompt", "rewrite this prompt", "optimize prompt" | Prompt refinement |
If multiple intents apply, pick the operation that matches the strongest verb in the prompt. If still ambiguous, default to recap (cheapest) and offer follow-ups.
Operations
1. Session Completion (done)
Capture progress before context evaporates โ typically the highest-leverage moment in an ADHD work session.
Canonical procedure: the full session-completion flow lives in
references/done.md โ the single source of truth shared
with the /craft:finish slash shim. For anything beyond the quick
summary below (Settings Sync, Memory Optimize, Insights Capture, Worktree
Status, the interactive summary, auto-git), load references/done.md and
follow it. Never reimplement that flow here or in the command shim. See
ADR-002.
Inputs: git status, git log --since="4 hours ago", current .STATUS file.
Quick summary (full detail in references/done.md):
- Gather session activity โ uncommitted changes, recent commits, files modified.
- Summarize what was accomplished in 3โ5 bullets, plain language.
- Update
.STATUS file: "โ
Just Completed", "๐ฏ Next Action", "๐ด Blockers".
- Sync CLAUDE.md, audit settings drift, capture + optimize memory, write the insights facet (see reference for the exact steps).
- Suggest a conventional-commits message; surface follow-ups (open PRs, failing tests, half-written specs).
Producer role: This is the upstream data producer for /recap, /next, and /craft:hub โ make .STATUS writes accurate and complete.
2. Context Restoration (recap)
Quickly answer "where did I leave off?" โ the opener for any returning session.
Sources (priority order):
.STATUS file (most authoritative) โ "โ
Just Completed", "๐ฏ Next Action", "๐ด Blockers" sections.- Recent git activity (last 48h) โ
git log --oneline --since="48 hours ago".
- Open PRs / issues via
gh pr list --author @me --state open and gh issue list --assignee @me. When issues are returned, suggest /craft:git:issue-check <N> to check whether each issue's premise still holds before resuming work on it โ not a broader GitHub-attention scan (no such skill exists; v1 scope is issue-premise-check only).
- Project planning files โ
TODO.md, PLAN.md, ROADMAP.md, CLAUDE.md.
- Obsidian sync config โ run
obs doctor --layer flow --json (if .flow/ exists). Report flow-sync-missing as โ ๏ธ + suggest obs flow init; report flow-sync-stale as โ ๏ธ + suggest obs flow init to update. Never block on flow warnings โ they are informational.
Output: Short, scannable summary โ what was completed, what's next, what's blocked. Aim for under 20 lines.
3. Next-Task Suggestion (next)
Cut decision paralysis by suggesting one clear next task โ not a menu of five.
Priority order:
- Unblocked items (was waiting, now ready).
- In-progress work (maintain momentum).
- Quick wins (< 15 min, builds confidence).
- Important but not urgent.
- Blocked items โ acknowledge but don't suggest.
Output: One recommendation with a one-sentence rationale. Offer at most one alternative if there's a close second.
4. Focus Mode (focus)
Commit to one task and block mental distractions.
Steps:
- Confirm the task โ accept
/next's suggestion, or take a user-supplied task description.
- Set focus parameters โ suggested duration (25 min Pomodoro / 45 min standard / 90 min deep work).
- Display a focus banner with the task, time budget, and "what to ignore" reminders.
- Capture distractions to a list ("come back to these later") rather than acting on them.
5. Unblock Helper (stuck)
Targeted help when the user can't move forward.
Six common stuck types โ ask which applies, then route:
| Type | Diagnostic | Routing |
|---|
| ๐ต Don't know where to start | Goal unclear or task too big | Smallest-first-step breakdown |
| ๐ค Don't understand something | Knowledge gap | Explain, link docs, or dispatch an Explore agent |
| ๐ง Technical problem/error | Bug or env issue | Suggest /craft:code:debug or /bug-detective |
| ๐ฐ Overwhelmed by scope | Task too big | Break into 15-min subtasks |
| ๐งฑ Waiting on something external | True blocker | Acknowledge, suggest parallel work |
| ๐ด Can't focus today | Energy issue | Suggest break, quick win, or non-coding task |
6. Spec Review (spec-review)
Interactive review of formal specs in docs/specs/SPEC-*.md.
Sub-actions:
| Action | Behavior |
|---|
list (default if no topic) | Enumerate specs with status |
show <topic> | Display spec content |
review <topic> | Validate frontmatter, walk acceptance criteria, prompt for status updates |
approve <topic> | Mark Status: approved |
archive <topic> | Move to docs/specs/archive/ (completed work) |
Validation checks on review:
- Frontmatter parses (
Status:, Created:, Related plan: fields).
- Acceptance criteria are testable (each maps to a check).
- Open questions don't block the current batch.
- History table is up to date.
7. Prompt Refinement (refine)
Rewrite vague prompts into specific, well-structured requests.
Steps:
- Get the prompt โ argument or interactive.
- Diagnose โ what's missing? (goal, constraints, success criteria, context, format).
- Rewrite โ produce a clearer version that names the goal, constraints, expected output, and any project context the user implied.
- Explain โ short bullet list of what changed and why, so the user learns the pattern.
Anti-patterns to fix: "help me with X" (no goal), "make it better" (no criteria), "fix this" (no context), missing file paths, missing acceptance criteria.
Cross-Operation Data Flow
This skill participates in a producer-consumer-reflector pattern with the rest of craft:
- Producer:
done writes .STATUS, commits, memory entries.
- Consumer:
recap, next, focus, stuck read .STATUS and session history before acting.
- Reflector:
/craft:hub aggregates the state into a dashboard.
Always read .STATUS first when restoring context. Always update .STATUS last when completing a session.
ADHD-Friendly Output Principles
- One decision at a time โ never offer 5 options when 1 will do.
- Visual hierarchy โ headers, tables, emoji markers (๐ฏ โ
๐ด ๐ง) for scannability.
- Concrete next step โ every operation ends with a clear, actionable suggestion.
- Quick wins highlighted โ explicitly label items under 15 minutes.
- No "while you're here" โ stay scoped to the operation requested; capture-and-defer everything else.
Integration
This skill replaces the seven commands/workflow/*.md commands during the v2.34.0 โ v3.0.0 migration:
/done โ operation 1 (Session Completion)/recap โ operation 2 (Context Restoration)/next โ operation 3 (Next-Task Suggestion)/focus โ operation 4 (Focus Mode)/stuck โ operation 5 (Unblock Helper)/spec-review โ operation 6 (Spec Review)/refine โ operation 7 (Prompt Refinement)
Both invocation paths work during the deprecation cycle. The skill auto-fires on natural-language match; explicit slash paths continue to function until v3.0.0 โ /craft:finish (renamed from /craft:done, ADR-006), /craft:next, and /craft:refine are now root commands (promoted from workflow:), while /craft:workflow:recap, /craft:workflow:focus, and /craft:workflow:spec-review remain nested.
For ADHD-friendly workflow strategy prose (not an operation, no behavior), see references/adhd-guide.md.
Related Skills
mode-controller โ switches execution mode (default/debug/optimize/release) orthogonally to these operations.project-planner โ for multi-week project breakdowns (this skill handles session-scope; project-planner handles project-scope).release โ when the next action is "ship it".
