IF A SKILL APPLIES TO YOUR TASK, YOU DO NOT HAVE A CHOICE. YOU MUST USE IT.

This is not negotiable. This is not optional. You cannot rationalize your way out of this. </EXTREMELY-IMPORTANT>

How to Access Skills

In Claude Code: Use the Skill tool. When you invoke a skill, its content is loaded and presented to you — follow it directly. Never use the Read tool on skill files.

In other environments: Check your platform's documentation for how skills are loaded.

Using Skills

The Rule

Invoke relevant or requested skills BEFORE any response or action. Even a 1% chance a skill might apply means that you should invoke the skill to check. If an invoked skill turns out to be wrong for the situation, you don't need to use it.

digraph skill_flow {
    "User message received" [shape=doublecircle];
    "About to EnterPlanMode?" [shape=doublecircle];
    "Already brainstormed?" [shape=diamond];
    "Invoke brainstorming skill" [shape=box];
    "Might any skill apply?" [shape=diamond];
    "Invoke Skill tool" [shape=box];
    "Announce: 'Using [skill] to [purpose]'" [shape=box];
    "Has checklist?" [shape=diamond];
    "Create TodoWrite todo per item" [shape=box];
    "Follow skill exactly" [shape=box];
    "Respond (including clarifications)" [shape=doublecircle];

    "About to EnterPlanMode?" -> "Already brainstormed?";
    "Already brainstormed?" -> "Invoke brainstorming skill" [label="no"];
    "Already brainstormed?" -> "Might any skill apply?" [label="yes"];
    "Invoke brainstorming skill" -> "Might any skill apply?";

    "User message received" -> "Might any skill apply?";
    "Might any skill apply?" -> "Invoke Skill tool" [label="yes, even 1%"];
    "Might any skill apply?" -> "Respond (including clarifications)" [label="definitely not"];
    "Invoke Skill tool" -> "Announce: 'Using [skill] to [purpose]'";
    "Announce: 'Using [skill] to [purpose]'" -> "Has checklist?";
    "Has checklist?" -> "Create TodoWrite todo per item" [label="yes"];
    "Has checklist?" -> "Follow skill exactly" [label="no"];
    "Create TodoWrite todo per item" -> "Follow skill exactly";
}

Red Flags

These thoughts mean STOP — you're rationalizing:

Skill Priority

When multiple skills could apply, use this order:

1. Process skills first (brainstorming, debugging) - these determine HOW to approach the task
2. Implementation skills second (frontend-design, mcp-builder) - these guide execution

"Let's build X" →brainstorming first, then implementation skills. "Fix this bug" →debugging first, then domain-specific skills.

Task Complexity Assessment (MANDATORY — before skill routing)

Before routing to skills, assess whether the task is a simple or complex requirement.

Assessment Dimensions

All three Simple → propose Lightweight Track. Any one Complex → proceed with full skill workflow (brainstorming → writing-plans → executing-plans).

Assessment Presentation Format

Present to the user before proceeding:

Task Assessment:
- Requirement: [one-line summary]
- Scope: [file(s) or area]
- Impact: local / cross-component
- Dimensions: [Simple/Complex] × [Simple/Complex] × [Simple/Complex]

Proposed track: Lightweight / Full workflow
Confirm? (or correct if wrong)

Wait for user confirmation. User may override the assessment in either direction.

Lightweight Track

Execute in order after user confirms simple requirement:

Step 1 — Understand Requirement

Restate the requirement in your own words. Ask: "Is this understanding correct?" Wait for confirmation before proceeding.

Step 2 — Create Lightweight Plans

Create docs/plans/YYYY-MM-DD-<feature-name>/ with two files:

02-design.md:

---
type: simple-requirement
track: lightweight
---

> **[Simple Requirement]** 本文件由轻量路径生成，非完整技术设计文档。

## Requirement
<!-- 做什么，为什么 -->

## Changes
<!-- 改哪里，怎么改 -->

97-risk-map.md:

---
type: simple-requirement
track: lightweight
---

> **[Simple Requirement]** 本文件由轻量路径生成。

## Known Risks
<!-- 已知风险或假设，无则填 none -->

Step 3 — Pre-Modification Gate

Present exactly what files and lines will change. Wait for confirmation per the Pre-Modification Gate rules below.

Step 4 — TDD

Apply agent-workflow:test-driven-development — write failing test first, then implement.

Step 5 — Commit

Use conventional commit format. Message MUST include requirement context (why), not only what changed:

fix(scope): add null check for userId parameter

Prevents NullPointerException when userId is absent from request
context, discovered in staging environment.

Step 6 — Standards-based Code Review

Invoke agent-workflow:requesting-code-review. Code reviewer finds 02-design.md with type: simple-requirement and applies Spec-based review against the lightweight design.

Skill Types

Rigid (TDD, debugging): Follow exactly. Don't adapt away discipline.

Flexible (patterns): Adapt principles to context.

The skill itself tells you which.

Pre-Modification Gate (MANDATORY BEFORE ANY FILE CHANGE)

Before executing any Edit, Write, or Delete operation, you MUST present a plan and wait for explicit confirmation.

Required Output Format

## Plan

**Changes:**
1. [file path] — [what and why]
2. [file path] — [what and why]
...

**Expected outcome:** [one sentence]

Waiting for confirmation.

Confirmation Rule

Only proceed after the user responds with an explicit confirmation (e.g., "yes", "go ahead", "确认", "可以").

Exceptions — May Proceed Without Confirmation

• User has specified the exact operation with no ambiguity (e.g., "rename X to Y in file Z") AND only one file is affected.
• User explicitly granted advance authorization in the same message (e.g., "直接改", "you decide", "just do it").

Cannot Be Bypassed — Always Confirm First

• Any change spanning 2 or more files.
• Any task where I am interpreting a goal into concrete actions (user stated WHAT, I am deciding HOW).
• Any file or directory deletion.

Red Flags — STOP, Do Not Proceed

Project Standards Gate (MANDATORY BEFORE CODING)

Before writing or editing code, load project-specific standards first:

1. rules/**/*.md in the current project
2. Root instructions (AGENTS.md, CLAUDE.md, project docs)
3. Existing code patterns in nearby files
4. Lint/format/type configs (eslint, prettier, checkstyle, spotbugs, etc.)

Priority order: project rules > language/framework skill > generic defaults.

If project rules conflict with a generic skill, follow project rules.

Error Memory Loop (DO NOT REPEAT MISTAKES)

When an error, failed review finding, or user correction appears:

1. Record it in a mistake log:
   • Project-level: docs/plans/YYYY-MM-DD-<feature-name>/99-mistake-log.md
   • Cross-project: docs/memory/global-mistakes.md (only reusable patterns)
2. Convert prevention into a concrete pre-check for the next similar step.
3. Re-check mistake logs before new edits and before claiming completion.

Minimum fields for each entry:

• Mistake
• Trigger
• Prevention check
• Status (open/resolved)

External Research Persistence Gate

Step 1 — Check local index before any web search

Before searching the web, check docs/research-index.md in the current project root:

• File does not exist → skip, proceed to web search.
• File exists, topic matches → read the linked 06-research-notes.md first. If the finding is still current (check Verified date and Recheck Needed field), use it directly without web search.
• File exists, no match → proceed to web search.

Step 2 — Persist new findings

When using web search or external documents for task decisions:

1. Persist findings in docs/plans/YYYY-MM-DD-<feature-name>/06-research-notes.md.
2. Include: Question, Source, Retrieved At, Key Findings, Decision Impact, Recheck Needed.

3. Add one row to docs/research-index.md (create the file if absent, using the template format):

   Keywords	Feature folder	Verified	Finding
   [searchable topic keywords]	docs/plans/YYYY-MM-DD-feature/	YYYY-MM-DD	[one-line summary of key finding]

4. If the insight is cross-project reusable, also add a distilled prevention/action entry to docs/memory/global-mistakes.md when relevant.

Do not rely on chat history alone for decision-critical external information.

User Instructions

Instructions say WHAT, not HOW. "Add X" or "Fix Y" doesn't mean skip workflows.

Knowledge Confidence Gate (MANDATORY)

Distinguish confirmed facts from inference and uncertainty at all times. Never express different confidence levels with the same tone.

When citing specific library methods, class names, annotation parameters, or version-specific behavior:

• Can confirm: state it directly
• Cannot confirm: say so and provide the verification path — never substitute a plausible-sounding guess for a verified fact

// CORRECT
@Transactional(propagation = Propagation.REQUIRES_NEW) opens an independent transaction.
Verify against current Spring version docs if behavior is critical.

// WRONG
@Transactional(isolation = Isolation.SNAPSHOT) is supported on MySQL.
(MySQL does not support SNAPSHOT isolation — this is a hallucination)

"I don't know" is a valid and correct answer. It is always better than generating confident-sounding but unverified content.

Version sensitivity: when behavior differs across versions, explicitly state which version the information applies to.