# `/decide` Skill Implementation Plan > **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. **Goal:** Build a user-invoked `/decide` skill that researches current industry best practice (WebSearch + context7 + GitHub) and either decides autonomously for reversible actions or escalates with factual-context questions for contested ones. **Architecture:** Single `SKILL.md` file at `~/.claude/skills/decide/SKILL.md`. The "code" is structured markdown instructions that Claude reads at invocation time. No external dependencies, no Python/TS, no traditional test framework — validation is performed by invoking `/decide ` and checking that the output conforms to spec sections. **Tech Stack:** Claude Code skill (YAML frontmatter + markdown), git versioning under `~/.claude/skills/.git`. Tools used at runtime: WebSearch, mcp__context7__resolve-library-id, mcp__context7__query-docs, mcp__github__search_code, mcp__github__search_repositories. **Spec reference:** `~/docs/superpowers/specs/2026-05-03-decide-skill-design.md` --- ## File Structure - Create: `~/.claude/skills/decide/SKILL.md` — the entire skill (frontmatter + body) - Modify: none - Test: smoke tests via interactive `/decide` invocation in a fresh Claude Code session Single-file skill. No supporting scripts, no helpers, no tests directory. The spec sections map 1:1 onto SKILL.md sections. Working directory for git operations: `~/.claude/skills/` (separate git repo, confirmed via `ls -la` showing `.git/`). --- ## Task 1: Scaffold skill directory and frontmatter **Files:** - Create: `~/.claude/skills/decide/SKILL.md` - [ ] **Step 1: Verify the parent directory and confirm no name collision** Run: ```bash ls -la ~/.claude/skills/decide 2>&1 ``` Expected: `No such file or directory` (skill does not yet exist). If the directory already exists, STOP and inspect — do not overwrite. - [ ] **Step 2: Create the directory** Run: ```bash mkdir -p ~/.claude/skills/decide ``` Expected: silent success. - [ ] **Step 3: Write frontmatter-only SKILL.md** Write to `~/.claude/skills/decide/SKILL.md`: ```markdown --- name: decide description: | User-invoked research skill. Investigates current industry best practice via parallel WebSearch + context7 + GitHub adoption signals, then either decides autonomously (reversible actions) or escalates with factual-context questions (contested or information-requiring decisions). Manually triggered via `/decide` only — never auto-invoked. Use when the user types `/decide` optionally followed by a question. Without arguments, extract the pending decision from the prior assistant message. allowed-tools: - WebSearch - WebFetch - mcp__context7__resolve-library-id - mcp__context7__query-docs - mcp__github__search_code - mcp__github__search_repositories - mcp__github__list_commits - Read - Write - Edit - Bash - AskUserQuestion --- # /decide — Best Practice Research & Autonomous Decision (body to be filled in subsequent tasks) ``` - [ ] **Step 4: Verify YAML frontmatter parses** Run: ```bash python3 -c "import yaml,sys; doc=open('$HOME/.claude/skills/decide/SKILL.md').read().split('---')[1]; yaml.safe_load(doc); print('YAML OK')" ``` Expected: `YAML OK` If this fails, inspect for indentation or quoting errors and re-run before proceeding. - [ ] **Step 5: Commit scaffold** Run: ```bash cd ~/.claude/skills && git add decide/SKILL.md && git commit -m "feat(decide): scaffold skill directory and frontmatter" ``` Expected: 1 file changed. --- ## Task 2: Write trigger and input resolution sections **Files:** - Modify: `~/.claude/skills/decide/SKILL.md` (append to body) - [ ] **Step 1: Append Trigger and Input Resolution sections** Use Edit to replace the placeholder line `(body to be filled in subsequent tasks)` with the following content: ````markdown ## When to Run Only when the user types `/decide`, optionally followed by a question. Never auto-invoke. The description gate above explicitly forbids automatic firing. ## 1. Input Resolution Resolve the question to research using these rules in order: 1. **If `/decide` is followed by text** → use the text verbatim as the question. Do not paraphrase. 2. **If `/decide` has no arguments** → scan the most recent assistant message in this conversation for a pending decision. Look for: - Sentences ending with `?` that contain choice indicators: `A) ... B) ...`, `X vs Y`, the words `which`, `어느`, `어디`, `뭐가` - If exactly one candidate is found, use it - If multiple candidates, use the most recent one and announce: `Researching: . If wrong, re-run with /decide .` - If none found, output exactly: `What should I research? Give me the question.` and STOP. Do not call any research tool. 3. **Once resolved**, announce: `Researching: ` (one line, then proceed). ```` - [ ] **Step 2: Read the file back and verify structure** Run: ```bash grep -c "^## " ~/.claude/skills/decide/SKILL.md ``` Expected: `2` (the `## When to Run` and `## 1. Input Resolution` headers). - [ ] **Step 3: Commit** Run: ```bash cd ~/.claude/skills && git add decide/SKILL.md && git commit -m "feat(decide): add trigger and input resolution sections" ``` --- ## Task 3: Write research pipeline section **Files:** - Modify: `~/.claude/skills/decide/SKILL.md` (append) - [ ] **Step 1: Append Research Pipeline section** Use Edit to add to the end of the file: ````markdown ## 2. Research Pipeline Once the question is resolved, run research tools. **WebSearch is always called.** The other two are conditional. ### Step 2a — Always call WebSearch (1-2 queries) Choose query patterns matching the question type: - Comparison: ` vs 2026 best practice` - Standard lookup: ` current standard 2026 recommended` - Workflow: ` recommended workflow order 2026` Prefer recent (≤ 18 months) sources. Prioritize: - Official framework/library team docs and blog posts (e.g., Vercel, Anthropic, Postgres team) - Industry surveys: State of JS, Stack Overflow Developer Survey, JetBrains Developer Ecosystem - Named expert blogs and conference talks **Stars and follower counts are not best-practice signals.** They correlate with hype and age, not technical correctness. ### Step 2b — Conditionally call context7 **Trigger:** the question mentions a named library, framework, or tool (Next.js, PostgreSQL, FastAPI, React, Pydantic, etc.). If triggered: 1. `mcp__context7__resolve-library-id` with the library name 2. `mcp__context7__query-docs` with the resolved ID and a topic-focused query (e.g., `"authentication recommended approach"`) If no library noun is detected in the question, skip this step. ### Step 2c — Conditionally call GitHub MCP (tiebreaker only) **Trigger:** Step 2a results show genuine disagreement between sources, OR Step 2a + 2b return no clear consensus. If triggered, use `mcp__github__search_code` or `mcp__github__search_repositories` to check **flagship adoption signals**, in this priority: 1. Adoption by major orgs / well-known production projects 2. Recent commit activity (last 6 months) and active contributor count 3. Star count is the weakest signal — use only as a final tiebreaker If Step 2a + 2b already converge, skip this step. ### Synthesis After tools return: - **All called sources point to the same answer** → "clear standard" → proceed to Section 3 - **Sources disagree, but the disagreement is explained by a project-context variable** (e.g., self-hosted vs managed, team size, scale) → proceed to Section 4 (escalate with factual-context question) - **Sources disagree without a clear discriminating variable** → proceed to Section 4 with the explanation that expert consensus is unclear ```` - [ ] **Step 2: Verify section count** Run: ```bash grep -c "^## " ~/.claude/skills/decide/SKILL.md ``` Expected: `3`. - [ ] **Step 3: Commit** Run: ```bash cd ~/.claude/skills && git add decide/SKILL.md && git commit -m "feat(decide): add research pipeline with conditional tool routing" ``` --- ## Task 4: Write clear-standard output format **Files:** - Modify: `~/.claude/skills/decide/SKILL.md` (append) - [ ] **Step 1: Append clear-standard output section** Use Edit to add to the end of the file: ````markdown ## 3. Output — Clear Standard Path When synthesis yields a clear standard, output exactly this structure: ``` **Decision: ** <2-3 sentences explaining why X is the current industry standard. Cite explicitly which type of source backed this: official docs, industry survey, expert consensus.> Sources: - - - Considered: , reason: ``` **Rules:** - Source URLs are mandatory. Never omit them — the user's global `` rule requires it. - Keep the explanation to 2-3 sentences total. Compact decision text, not a research summary. - The "Considered" line is mandatory whenever a real alternative exists. Naming the loser builds trust that the search was thorough. After this output block, proceed to Section 5 (Action Gate). ```` - [ ] **Step 2: Commit** Run: ```bash cd ~/.claude/skills && git add decide/SKILL.md && git commit -m "feat(decide): add clear-standard output format" ``` --- ## Task 5: Write contested escalation section **Files:** - Modify: `~/.claude/skills/decide/SKILL.md` (append) - [ ] **Step 1: Append contested escalation section** Use Edit to add to the end of the file: ````markdown ## 4. Output — Contested / Context-Required Path When synthesis is contested or the decision depends on a project-context variable, output exactly this structure: ``` **No clear standard — your context decides.** 업계 의견 분기: -

decide

Install this skill

Comments