Think Notes Skill

This skill appends a structured observation record to docs/skills/think.md whenever an agent response fails to meet user expectations on the first attempt.

The file is a long-lived experience log — not a task summary. Each entry records one real gap found during development so it can later be refined into a stable skill, rule, or checklist item.

When to trigger

Trigger whenever any of these signals appear after at least one agent turn:

• User reports a bug, regression, or wrong output from the previous agent response
• User calls out a missed requirement ("you forgot X", "this doesn't handle Y")
• User raises an ambiguity that was silently resolved the wrong way
• User corrects a design or architecture decision made by the agent
• User finds that an existing test, lint check, or build broke after the agent's changes
• User points out a run-time warning or console error introduced by the agent

Do not trigger for first-turn questions or clarifications that haven't produced any agent output yet.

What to record

Focus on the structural pattern that caused the failure, not the surface fix.

Ask yourself:

• Which category best describes this gap? (see categories below)
• What should have been checked but wasn't?
• Can this become a general rule that would prevent the same gap next time?

Failure categories (use these as labels in the record)

Category	Typical examples
constant-ownership	Constants / icons defined inline in a component instead of the shared entity layer
whitelist-completeness	New enum value added but not propagated to every whitelist branch
event-chain	Interaction bug fixed in one handler but default browser behaviour not blocked upstream
runtime-warning	Build/type checks pass but console emits warns at runtime (duplicate ext, prop mismatch, …)
generated-file	Build artefact or cache file committed to version control
test-sync	Test assertion still references the old counts / shapes after an implementation change
scope-creep	Agent modified more than requested, introducing unrelated breakage
missing-context	Agent assumed wrong context (wrong file, wrong module, wrong API contract)
other	Uncategorised; add a short label in the record title

How to write the entry

Read docs/skills/think.md first to understand existing records and avoid duplicates.

Then append (never overwrite) a new section using this exact template — translate the field labels to Chinese as shown, keep surrounding markers intact:

### [YYYY-MM-DD] <task-id or short title> — <category-label>

#### 背景

- <1–3 bullets: task context, which feature/PR/session, what the agent was asked to do>

#### 需求

- <1–3 bullets: what the agent should have produced or checked>

#### 结果

- <2–5 bullets: actual gap found, root cause, what was wrong or missing>

#### 预期

- <1–4 bullets: the rule, checklist item, or future skill that would prevent this>

Rules for the content:

• Use Chinese for the section body (背景/需求/结果/预期) to match the existing file style
• Keep each bullet concise (one sentence max)
• The 预期 section is the most important — it must state an actionable future rule, not just restate the problem
• Do not paraphrase or expand existing records; only append new ones
• After appending, confirm to the user with one sentence, e.g.: "已追加一条记录到 think.md（{title}）"

After Recording: Promote the Pattern

Appending the note is the minimum step, not the end state, when the pattern is already recurring or high impact.

After you add a record, decide whether the gap should update a repository resource in the same task.

Resource layer	Use when the pattern means...	Typical examples
.github/copilot-instructions.md	the rule should apply in almost every task	resource-promotion workflow, repo-wide verification expectations
.github/instructions/*.md	the rule is specific to a package, file family, or subsystem	viewer layering, useSyncExternalStore snapshot contract
.github/skills/*	the fix requires a repeatable multi-step workflow or audit	browser-based viewer review, package-local verification flow
.github/agents/*.agent.md	the workflow benefits from a stable role with explicit tool boundaries or handoffs	planner -> implementer -> reviewer orchestration
nearest AGENTS.md	the missing context was commands, navigation, or local entry points	package test commands, key runtime entry files
tests	the regression is deterministic and should be locked down automatically	snapshot stability, source resolution, lifecycle cleanup

Promotion rules:

• Prefer updating the matching resource in the same task when the note represents an already repeated or high-impact miss.
• If the pattern is not ready to be codified immediately, leave a concrete follow-up note that names the target resource layer.
• In this repository, treat docs/skills/think.md as an active promotion backlog rather than a permanent archive. Once a pattern has been fully promoted and no longer needs active follow-up, remove the full record from think.md instead of leaving a stale status suffix behind.
• Before deleting a promoted record, make sure the durable resource now captures the rule clearly enough that future tasks can discover it without the old think entry.
• Keep unresolved or partially promoted records in think.md; delete only entries whose rule has been absorbed into formal resources.

Example entry

### [2026-03-26] FEAT-002 标记工具增强审查 — whitelist-completeness

#### 背景

- 本次任务是 FEAT-002：新增图形笔图元、高亮透明度和拖动标记时避免误选 PDF 文本。

#### 需求

- 新增图元后，所有基于白名单的分支（归一化、渲染、移动、命中、测试断言）都应同步更新。

#### 结果

- `axis`、`heart` 绘制结束后位置异常，原因是 `use-mark-draft.ts` 的矩形归一化白名单漏掉了这两个新图元。
- 测试断言仍断言 shape 数量为 10，未随实现同步更新。

#### 预期

- 以后凡是新增枚举值/联合类型，必须同时核对所有基于白名单的分支：归一化、渲染、移动、命中、测试断言。