plan-debug

plan-debug is a skill for Claude Code, Codex from weiyi88/cc-code. It costs 24 tokens per session (3,120 once invoked), scanned A, original, MIT.

A guided bug-diagnosis workflow that investigates a known problem in planning mode before any code changes. It records the confirmed bug, its cause, and affected areas for a later repair step.

In plain words
What is it for?
Use it to clarify a bug, trace its code paths and likely impact, compare expected behaviour with the current implementation, and record a numbered bug for an execution agent.
Why use it?
It prevents guesses about the intended behaviour and separates diagnosis from implementation. It also stops changes when fixing the issue would require changing the documented product rules or API contract.

Skill for Claude CodeCodex

Written for Claude Code and Codex: allowed-tools in frontmatter, but also agents/openai.yaml present. Also seen: names the ExitPlanMode tool; mentions Codex.

Part of the cc-code plugin — 17 skills, 3 agents, 1 hook shipped together

Good fit Use it to clarify a bug, trace its code paths and likely impact, compare expected behaviour with the current implementation, and record a numbered bug for an execution agent.

Compare 6 skills from other repositories ↓
Install with agentmods
npx agentmods add skills/weiyi88/cc-code/plan-debug
Install

Getting it into your agent

One page per mod, every tool's command on it. A separate URL per tool would split the same page into five that compete with each other.

Any agent
npx skills add weiyi88/cc-code --skill plan-debug
Clone the repo
git clone --depth 1 https://github.com/weiyi88/cc-code

Made for: Claude Code, Codex.

Or install cc-code, the plugin that ships this one along with the rest of its 17 skills, 3 agents, 1 hook.

Wrote this? Show the measurements

A badge with what this costs and how it scanned, read live from this page, so it follows the numbers instead of freezing them. Markdown for a README, HTML for a documentation site or a project page.

agentmods badge for plan-debug

README.md
[![agentmods](https://agentmods.dev/badge/skills/weiyi88/cc-code/plan-debug/github.svg)](https://agentmods.dev/skills/weiyi88/cc-code/plan-debug)
Your own site
<a href="https://agentmods.dev/skills/weiyi88/cc-code/plan-debug"><img src="https://agentmods.dev/badge/skills/weiyi88/cc-code/plan-debug/github.svg" alt="Measured on agentmods" height="20"></a>

Or the 80×15 button, for a site that already has a row of RSS and ATOM ones. Only the verdict fits; the numbers stay here.

agentmods 80×15 button for plan-debug

Your own site · 80×15
<a href="https://agentmods.dev/skills/weiyi88/cc-code/plan-debug"><img src="https://agentmods.dev/badge/skills/weiyi88/cc-code/plan-debug.svg" alt="Reviewed on agentmods" width="80" height="20"></a>
Per session 24 Skills are progressive disclosure: only the name and description are preloaded; the body loads when the skill is used.
When invoked 3,120 The whole file, excluding the scripts and references it only reads on demand.
Security scan A 0 findings. A grade says what 26 rules found in the file — not that it is safe.
Origin original No closer match found in the catalogue.
Token cost

What it costs to keep this loaded

Counted locally with the o200k_base tokenizer, which is exact for GPT models; Claude uses its own tokenizer and its counts differ. Treat this as one consistent yardstick across the catalogue rather than a bill. Prices are per million input tokens.

ModelPer sessionOnce invoked
Fable 5.1 $0.00024 $0.03120
Opus 5.5 $0.00010 $0.01248
Sonnet 5.5 $0.00005 $0.00624
Haiku 4.5 $0.00002 $0.00312

Measured today against content hash da5f507943ac, method: parsed. Prices are Anthropic first-party input rates as of 2026-10-07, from the pricing page.

Security

Grade A, and why

plan-debug scanned grade A with 0 findings against 26 rules in 11 categories — prompt injection, anti-refusal, data exfiltration, privilege escalation, supply chain, agent snooping, system-prompt leakage, SSRF and excessive agency — measured today.

A static scan of the body, not an audit. Every finding is printed with the line that produced it so you can judge whether it matters here. A mod is markdown that instructs an agent; that is exactly why what it instructs is worth reading.

Nothing flagged

None of the 26 patterns this scan looks for appear in this file: no shell pipes, no recursive deletes, no credential paths, no hidden text, no instruction-override or anti-refusal phrasing, no agent-config snooping. That is not a guarantee, it is the absence of the things that are checkable.

skills/plan-debug/SKILL.md · 219 lines

How it starts

The opening of the file, as written. The whole thing — 219 lines — stays where its author put it; the contents beside it link to each section on GitHub.

/cc-code:plan-debug — bug 诊断器(第一动作即 plan 模式)

⭐⭐⭐ 触发后第一动作 = call EnterPlanMode 工具。 ⚙️ 引擎分支(双端同一条规则):无 EnterPlanMode 工具的引擎(如 Codex)→ 第一动作改跑 Bash mkdir -p .cc_code/.runtime && touch .cc_code/.runtime/plan-lock 开护栏(此后写盘被 gate.sh 拦),出关经主人确认落盘清单后 rm .cc_code/.runtime/plan-lock。 所有问诊 / 侦察 / 三件套 / 交谈都在 plan 模式内做,没有 plan 外窗口。 定位:技术诊断器,不是需求规划器。 与 /cc-code:plan-feature 的分界:那个处理「需求模糊」,本命令处理「需求明确但实现错了」—— bug 本身就是需求,期望行为要么主人说了、要么 prd.md 已有断言。 配对:本命令落盘 B-n 后,修复执行走 /cc-code:agent-debug(增量定位 B-n → Dev→QA → affected 精准回归)。

⛔ 六条铁律(违反任一即本次诊断无效)

铁律 1:第一动作 call EnterPlanMode

触发后,在 call EnterPlanMode 之前,不许做任何动作:

  • ❌ 不许先 Read Agent.md / status.md
  • ❌ 不许先 codegraph 探测
  • ❌ 不许先输出三件套
  • ✅ 唯一允许的第一动作:call EnterPlanMode 工具

铁律 2:期望行为唯一来源 = 主人原话 + 既有 A/U 断言

这是 plan-feature 铁律 2 在 debug 线的移植 —— 诊断时最容易犯的错就是拿实现当期望。

期望行为的合法出处:
  ✅ 主人在对话里的原话
  ✅ prd.md §1.5 的既有 A 断言
  ✅ ux.md §2.3 的既有 U 判定项

  ⛔ 绝不许从「代码现状」反推「所以期望应该是 X」
  ⛔ 绝不许从 codegraph 产出反推期望 —— codegraph 只答「代码现在是什么样」

铁律 3:裁决门(bug ↔ 迭代的分界)

满足任一即拒修,指路 /cc-code:plan-feature,本命令到此为止:

① 修复需要改 api.md / data.md 契约
② 修复需要改 prd.md / ux.md 需求(新规则 / 新断言 / 新交互态)
③ 期望行为在合法出处里找不到,且主人不愿当场拍板

「深层 bug 牵涉多文件」不是拒修理由 —— 影响面大小是事实问题,由 impact / affected 沿 import 图算出,不由规划仪式回答。动契约才拒修,不动契约再深也修。

铁律 4:三件套只确认不落盘

三件套服务当轮对话裁决,主人 ExitPlanMode 确认即弃。落盘物仅两处:bugs.md 的 B-n 条目 + status.md 一行指针。

铁律 5:B 编号独立序列

bugs.md 的 B-n 独立递增(读已有最大号取下一个),绝不复用 A/U 序列(那两个永久稳定,bug 断言生命周期是天级)。条目修完即删,不占 active 篇幅。

铁律 6:越权红线

⛔ active/prd.md / ux.md / api.md / data.md / project.md —— 本 skill 绝不改写
⛔ active/gates.md                                          —— QA 唯一域
⛔ src/ 与测试目录                                          —— Dev 唯一域
✅ active/bugs.md 新条目 + status.md「下一步」一行           —— 唯一落盘动作

一、生命周期总览

触发 /cc-code:plan-debug "<bug 描述>"
  │
Step0 ⭐ call EnterPlanMode(第一动作,Write/Edit 当场锁死)
  │ ══════════════ 以下全程 plan 模式内(只读 + 文字输出)══════════════
Step1 把 bug 问清楚(逐点提问,一次一个模糊点,禁批量决策清单)
  │   问什么:现象 / 复现步骤 / 期望行为(当场要出处:主人原话 or 既有 A/U 断言)
  │
Step2 codegraph 四路调查脉络(只取事实)
  │   ⓪ 新鲜度保险 → status --json:pendingChanges 非 0 则先 sync
  │   ① explore(bug 现象关键词) → node(涉事符号)  读现状
  │   ② callers(涉事符号)                        追触发链路
  │   ③ impact(核心符号)                         传递闭包真半径
  │   ④ affected(涉及文件)                       测试影响面
  │   CLI 未装 → 降级 Glob/Grep 表层扫描,三件套标注「半径为估算」
  │
Step3 根因定位(根因 = 一句话说得清的因果链;说不清 → 回 Step1 继续问)
  │
Step4 裁决门(铁律 3 三条逐一检查)
  │   ├─ 命中任一 → ⛔ 拒修:「这不是 bug 修复,是迭代,请走 /cc-code:plan-feature」
  │   └─ 全过 → Step5
  │
Step5 输出三件套(bug 版,ascii)
  │   ① 逻辑图:bug 触发链路(只画逻辑,无函数无代码)
  │   ② 差异表格:现状(实然) vs 期望(应然) vs 修复方案 逐行对齐
  │   ③ ASCII 前端原型:仅涉前端改动时给(修前 / 修后对比)
  │
Step6 逐点交谈至通顺(主人对根因/方案有疑 → 修 → 刷新三件套)
  │
Step7 call ExitPlanMode → 主人确认三件套
  │ ══════════════ 退出 plan 模式 ══════════════
Step8 落盘(确认即授权)
  │   bugs.md 新条目 B-n(复现/期望出处/根因/日志证据/需加探针/方案/影响面,≈17 行)
  │   status.md「下一步」→ B-n 待修复(一行指针)
  │   提示主人走 /cc-code:agent-debug

Read the full file on GitHub · 219 lines

Files

What ships with it

1 file beside SKILL.md in the same directory: the scripts, references and assets a skill reads on demand. Not counted in the per-session cost; read them before you install if any of them is executable.

Changes

What this file has done since we first saw it

Hashed on every crawl. A supply-chain change to an agent config is a question of when, not whether, so the history is kept rather than the latest state alone.

  1. today Changed · +5 lines da5f507943ac
  2. 1mo ago Changed · +1 lines 37524a28046a
  3. 1mo ago Changed · -192 tokens per session 11c2790603d6
  4. 1mo ago First seen · 213 lines · 216 tokens per session scan A 85719f901d17

Subscribe to this mod's changes

plan-debug is a skill published in the GitHub repository weiyi88/cc-code (5 stars, last pushed yesterday), licensed MIT. It adds 24 tokens to every session and 3,120 once invoked, about $0.0001 per session on Opus 5.5. A static security scan graded it A with 0 findings. No closer match exists in the catalogue, so it is treated as the original; first seen 2026-09-13.

Related

Other skills, from other repositories

rethink-unblock

Break out of a stuck approach by reframing a technical problem through structured thinking frameworks. Use when blocked, going in circles, or when a fresh perspective is needed on architecture, design, or debugging.

tae0y/python-project-template · 45 tokens

check

Check code quality without making changes — lint, format, type, and security checks. Use when you want to inspect issues before fixing them.

tae0y/python-project-template · 30 tokens

debugging-executions

Debug failed or wrong-output workflow executions using executions tools. Load when the user reports execution failures, unexpected node output, empty parameter values after a successful run, or a node showing a red or failed expression error. Also load when a live run you started for the user fails with an error from…

n8n-io/n8n · 86 tokens

n8n-docs-assistant

Answers n8n product, setup, credential, node, hosting, API, and usage questions from current n8n docs. Use when the user asks how to configure, set up, troubleshoot, or understand n8n behavior, especially credential setup questions — including which OAuth scopes or permissions a provider app needs.

n8n-io/n8n · 71 tokens

dorodango

Polishes working code through successive quality passes in fresh subagents. Use after tests pass when code needs multi-dimension refinement before release.

athola/claude-night-market · 31 tokens

sentry-sdk-upgrade

Upgrade the Sentry JavaScript SDK across major versions. Use when asked to upgrade Sentry, migrate to a newer version, fix deprecated Sentry APIs, or resolve breaking changes after a Sentry version bump.

getsentry/sentry-for-ai · 48 tokens