Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
A direct command skips the review prompt. Inspect the source before running it.
复盘 / 沉淀 / 总结经验 / 补进技能 / 技能缺陷 / 流程优化 / would other teammates hit this / will we forget next time / teamwide recurrence / extract skill / post-mortem / 深度 review·审计技能仓库 / 对标外部技能包找 gap（benchmark superpowers·gstack 等） / 核查全局安装点（~/.config/opencode 等）旧快照是否遮蔽本仓技能 / 本仓（ccl-skills 等共享技能仓）OpenCode 项目配置·命令治理 → turn reusable lessons into durable CCL skills.
Skill Extraction Workflow
Use this skill to turn observed experience into durable agent skills without copying business-specific codebase details. It complements public skill-authoring guidance such as writing-skills and skill-creator: those define skill format and authoring discipline; this skill defines how to mine, filter, generalize, validate, and land reusable CCL skills.
R0 (mandatory clean-landing gate): Before marking any skill or reference change R0-clean, landing-clean, merge-ready, or cleanly landed, run the leakage audit (audit_cmd from the maintainer's private alias YAML) and require zero hits across all leakage categories — design-source file keys/URLs/node-ids, project/team identifiers, real subproject paths / repo / branch names, contributor names/emails, ticket ids, internal domains/hosts, and any non-distilled business/product noun pointing to one specific organization.
Probe, don't infer: a local environment without ALIAS_AUDIT_CMD is normal, but you must observe that — before recording interim / r0_status, run check-ccl-skills.sh and cite the actual r0_status= / final-token line it produced; never infer the branch from "unset is common" or a bare printenv ALIAS_AUDIT_CMD pre-check. Skipping straight to the interim fallback is a blocked-verification miss (a set var means the private audit is configured; it is available only once it runs clean to alias_audit_ok, and a set-but-broken var is itself a blocked-verification failure to fix or waive, not a fallback licence).
Interim commit semantics: when ALIAS_AUDIT_CMD is genuinely unset, the contributor may commit, push, or open a Draft/WIP MR only as interim with R0 pending maintainer audit recorded, but must not merge or claim clean landing until R0 passes or an explicit risk-owner waiver is recorded. (Label semantics: interim alone does not decide commit permission — this R0-pending interim allows commit/push/Draft-MR but blocks merge/clean-landing, while the review/challenge gate's interim is an uncommitted checkpoint that blocks commit itself; each gate's failure carries its own commit permission, and when both fail the stricter applies.)
Edit-time gates that stay inline: every new sanitized label MUST already exist in the alias YAML before clean landing (fail-closed); pre-existing leakage may be known_debt but new/modified content MUST stay zero-hit; grep cannot catch source-shaped example identifiers (variable/function/class/file/package names lifted verbatim) so adversarial review (codex challenge or equivalent) is the practical safety net.
False-green guard: the public fallback is public interim evidence only — the private alias audit () has NOT run when those tokens print, so record and never treat , , , or as clean-landing R0 evidence; the clean-landing signal is (); no project alias is not a waiver (use the generic process-retro profile when no product corpus applies; neither the generic fallback nor an ad-hoc is the clean-landing gate).
Evidence, RCA, charter & attribution（证据 / RCA / charter / 出处核实）
Charter-before-editing red-line: do not read sources or edit skills until the complete charter in references/source-to-skill-extraction.md#extraction-charter is filled cell-by-cell. A remembered field subset is not a charter. Step 0 owns the procedure; this rule owns the hard stop. Core-Rule canonicality governs same-facet drift only and never narrows that field set to this bullet.
Classify every result — including task/session summaries and lessons-learned requests, not only failures — as failure/correction, stable success, or unstable/insufficient evidence. Failure runs RCA; stable success requires mechanism, non-luck evidence, reuse conditions, firing point, and owner; insufficient evidence stays an observation. Never invent a failure story to justify learning from success. The author classifies, so the class is not self-elective: correction/finding/failure-triggered work defaults to failure/correction, and only independent review may accept a relabel into an RCA-skipping class. Missing classification, unaccepted relabel, or missing analysis leaves it interim. Full method: references/source-to-skill-extraction.md#result-learning-baseline-for-every-extraction.
RCA must go wider than one 5-Why chain. 5 Why is the entry technique to get past a symptom, but a single linear chain to one "root cause" is its documented failure mode: real process/agent failures need multiple concurrent causes, the stop point is arbitrary, and "why" drifts toward "who"/blame.
For any non-trivial extraction, RCA must (a) widen — enumerate the multiple contributing factors across categories (trigger/routing, stale process-model, missing mechanical control, missing feedback, latent authored-earlier condition, detection gap) before deepening one — a straight chain with no branches means you stopped early; (b) counterfactually test each candidate to rank causal weight — if removed or changed, would the failure still happen? — keeping necessary/sufficient factors and failed redundant safeguards as secondary controls / defence-in-depth, and dropping only genuine coincidence (a one-trace factor is a hypothesis — mark it probabilistic, don't hard-drop); (c) frame prevention as a mechanical control on the failure CLASS — an enforced constraint plus the feedback that confirms it fired on a surface the next agent actually reaches in time (not a clause buried in a deep reference) — not agent diligence, preferring the highest-leverage practical control (a named artifact, an owner who can change it today, an observable check — never deleting a useful narrow gate or inflating one miss into an over-broad hook) over the first patchable point.
Missed-extraction diagnosis: if the user asks why extraction did not trigger or how to repair a missed extraction gate, treat that as a skill-extraction-workflow correction task first. Before method, testing, implementation, or product-specific advice, run correction RCA, classify the miss, create the target-output row for this workflow plus the owning target, record sibling/no-sibling or owner-generalization, and invoke or update the owning skill/project doc. A one-line routing note followed by method details is only interim, not a landed fix.
Per-round re-invocation: every new extraction round (different target skill / different domain / different source corpus / "提炼 X" / "extract industry best practices for X" / "borrow industry thinking for X") MUST start with a fresh skill-extraction-workflow Skill invocation by the agent, even when the workflow was invoked earlier in the same session.
Earlier invocations do not carry over — each round has its own charter, target-output map, sibling-generalization mini-map, and dual-track gate.
The agent cannot self-authorize to skip invocation by "running the pattern from memory" because prior rounds followed the same shape; doing so produces extractions that drift from the durable rule set without ever crossing the gate.
Failure shape: agent runs grep + drafts codex consult + lands diff, all without an in-session Skill invocation for this round → no charter, no RCA, no recorded target-output map → quality degrades silently round-over-round.
Closeout gate: for any commit touching a target skill, THIS round must have started with a skill-extraction-workflow invocation, evidenced by something checkable: a visible Skill invocation in the transcript when the host lets the agent (or reviewer) inspect it, otherwise the round's durable charter + target-output record (source-register row or session work note) that only the invoked workflow produces. Neither present ⇒ the commit is interim and the work cannot be reported as landed. (Most hosts do not let the agent read its own transcript — do not claim transcript evidence you cannot inspect; produce the durable record instead.)
Concurrent-session isolation applies before the FIRST edit, not merely before commit — this is delivery-wide and owned by product-rd-workflow's concurrent-session isolation rule (route there; it covers the host-install-symlink masking and the do-not-commit-unreviewed-to-dodge-clobber clause). So when any other session/agent/work-line may touch the repo, isolate (dedicated worktree/clone; multi-agent-delegation for parallel workers) before the first edit; if isolation was skipped, do NOT commit unreviewed shared-skill edits to dodge clobber — move the patch to a private worktree/scratch, commit only after the dual-track gate passes, and re-verify files on disk after any concurrent activity. This routes to that rule, not a second copy.
Map every owner/target before the first edit; verify the diff against it at closeout. Every non-wording extraction needs, before editing, a target-output / owner-generalization map listing every plausible owning skill/reference/workflow — derived from lifecycle impact (product intent, design/UX, implementation, debugging, testing, launch, iteration, onboarding, no-source-access usage), not from memory — each marked updated, unchanged, routed, not-applicable, or pending. Plausible owners include product workflow, testing, design, web/app/miniapp, backend stack, release, observability, security, test-artifact-management, and this workflow; if a lifecycle stage has no owner, state the no-output reason rather than silently omit it. At closeout the actual diff must match the map: updated rows have a real diff; unchanged/routed/not-applicable rows name the reason; any pending row blocks a complete claim. A passing static script (validate-skill.sh / check-ccl-skills.sh) does NOT prove the map ran, and independent review must block when the map is absent. Record the map durably — not in chat, PR text, commit message, or edits inside the target skill text; preferred format owner | direction(upstream/downstream/sibling) | status | changed-file-or-reason. One combined map covering the relevant directions (lifecycle owners, upstream/downstream, siblings) satisfies all the per-axis gates below at once. Wording-only edits use a one-line map (only spelling/grammar/formatting changed; all meanings, routing, and validation requirements unchanged). A source carrying both design judgment and implementation mechanics must update or explicitly skip BOTH the design and the dev skill. The impact-chain and sibling-stack maps below are scoped subtypes of this one obligation, not separate obligations.
Classify each candidate target's editability before editing (the user's "our/CCL/shared skill" challenge triggers this): mark each editable CCL target, reference-only external/system skill, local/private note, or discarded. External/system skills may guide method or routing but are not landing targets for reusable CCL behavior unless explicitly ccl-owned or vendored in the current repo and passing the normal shared-skill gates; otherwise route the lesson to CCL workflow text, a local/private note, or an upstream issue/PR — do not locally edit the installed external/system package. If a prior map treated a reference-only skill as editable, correct the map first, record the routing miss, and land the prevention in the smallest ccl-owned skill.
What to extract, content placement & domain (UI/UX) judgment（抽什么 / 内容放置 / 领域判断）
Extract behavior, decision rules, quality gates, evidence patterns, and routing boundaries; do not extract business nouns, repo names, IDs, one-off incidents, or stale implementation details.
Keep the skill entrypoint as the trigger and routing surface; move detailed variants, source-derived patterns, and examples into reference files. Each reference links one level from the entrypoint and stays inside the reference line budget; references/attention-budget-ratchet.md owns that budget, the write-side authoring norms, and the design invariants any size/budget gate must satisfy.
A skill must be executable, not only directional. For design, client, testing, debugging, or review skills, include concrete workflow steps, decision points, state/checklist coverage, and verification evidence so future agents do not produce work that is compliant but weak.
Design/client extraction must cover the judgment layer, not only the engineering layer. For UI/UX, extract aesthetic logic, interaction logic, behavioral logic, and user psychology from source evidence before landing rules about layout, components, breakpoints, or tests.
UI/UX judgment extraction must use observable proxies, not adjectives. Read state families, navigation/entry/return paths, disabled reasons, recovery controls, timing/feedback, accessibility, responsive/device variants, and code state machines before claiming behavioral or psychology rules. Use references/uiux-judgment-extraction.md for the required method.
UI/UX lessons usually route to multiple owners. Before editing, map each candidate to design, web, app, miniapp, testing, product workflow, or this extraction workflow using references/uiux-routing-map.md; do not land only the design rule when implementation or scenario testing is required. For mini-program lessons, testing-strategy owns layer/scenario selection, while miniapp-product-dev owns host-platform implementation, developer-tool or real-device evidence, review/release mechanics, and miniapp runtime constraints.
Judgment-layer extraction must name what changed. For UI/UX/client sources, record whether each judgment layer produced a new rule, confirmed an existing rule, narrowed an existing rule, or found no new evidence. If the pass only improves execution/validation, say so instead of implying new aesthetic, behavioral, psychology, or interaction knowledge.
For UI/UX/client extraction, the judgment-dimension axis enumeration lives in references/uiux-judgment-extraction.md. When the adjacency-scan rule fires on a UI/UX source, walk that enumeration — do not re-derive the axis list from memory.
A UI/UX judgment-delta row is not complete with labels such as confirmed, narrowed, or no new evidence alone. Each visual direction/tokens row must satisfy the field list in ; if those fields were not inspected, mark the row or and do not claim design-judgment extraction.
A reported recurring cross-project agent failure plus a question about a proposed prevention is a correction/extraction trigger. Run RCA and target-output mapping; chat-only advice cannot close it. If an owner rule already covers the issue, strengthen its firing path — or record the firing-path proof required by the unchanged: already-covered closeout rule — rather than returning a bare no-op. The same duty applies to two self-defect forms: the user asks whether THIS workflow itself has a defect after a missed extraction (classify trigger discovery / routing / target-output mapping / landing / validation, and update this workflow's owning rule even when another skill also changes); and repeated corrections show the workflow under-specified — the same failure class twice in one extraction thread stops normal extraction for the repeated-correction escalation protocol, lands the owning workflow/checklist/validation rule update, and only then resumes target-skill edits.
复盘 / 纠正 / retro / postmortem / bug-hunt / review-follow-up is an extraction by default, not a chat-only retro. Triggers (full duty): any standalone "复盘" / "沉淀" / retro / postmortem invoked as such — 复盘 is an extraction by default, no missed gate required; a missed testing/design/delivery/review gate followed by such a request or an equivalent user correction; any user correction about extraction quality; a retro/review/postmortem the user then challenges with "why wasn't this workflow used". Treat it as a process defect, not a conversation detail, and do not resume the in-flight extraction until the RCA is recorded:
(1) run RCA first — failed decision → root cause → missing skill rule/validation gate → durable prevention; (2) build a target-output map deciding for each kept lesson whether it belongs in a target skill, in this workflow, or both, mapping each to an owning skill/reference/process gate (include skill-extraction-workflow itself when the miss is routing/extraction/under-trigger behavior); (3) land the smallest durable prevention OR explicitly mark every candidate unchanged/routed/discarded with evidence (subject to bullet B path (i)'s always-land-here for failure-class exposures), and verify the final diff matches the whole map (not intent — every mapped target actually landed, not merely that one change is real). A chat-only owner recommendation is not enough.
When the user challenges why the workflow wasn't used, the earlier response is a failed extraction, not a completed retro — run the same correction RCA → map → land sequence; another chat-only explanation is not an answer. A final-response-only retro is allowed ONLY after a minimal RCA + candidate map where every candidate is explicitly //, with the source/evidence boundary stated. Ordinary bug-hunts / review follow-ups (not corrections) carry only the lighter duty — don't stop at the project outcome: decide target / this-workflow / both and make the diff match the map — without the stop-the-line RCA; routine bug/QA/review nits stay in their owner skill per the auto-trigger boundary below. If the extraction workflow itself allowed the shallow response, add the narrow guard HERE, not only in the downstream skill.
Validation & the dual-track gate（验证 / dual-track 门）
Static validation is not extraction validation. Nontrivial closeout shows the matching result analysis, target-output and sibling decisions, landed diff, commands, and independent review/challenge; otherwise report interim even if static checks pass.
For a whole-session/task-retrospective extraction over operational delivery that changed repositories, branches, MRs, pipelines, releases, or deployable artifacts, closeout validation must show one of: delivery-state rows with changed artifact, branch/worktree, remote/MR, CI/local verification, cancelled/retried, residual-risk, and next-action state; or artifact/status axis: not-applicable with the reason. Missing delivery-state evidence downgrades the extraction to interim; static validation and clean independent review do not close it.
A rule that exists but did not trigger is a validation-gate defect, not proof that the workflow is adequate.
For any correction where the missed step was covered by any rule in this workflow that a reasonable reader would apply to the scenario, add or tighten a closeout gate that would have blocked the exact premature final answer.
"The owner skill already states the rule" / "avoid monotonic growth" does NOT license a memory-only or no-op landing when the gate demonstrably failed to fire. If a rule exists yet the failure still happened (and would recur for another agent or project), adequate content is not adequate enforcement: land the firing mechanism — the trigger, closeout step, validator, or merged clause that makes the existing rule actually catch this case, in the owning shared skill — or prove it now fires. Retreating to a personal memory or "no change, content is fine" while the gate stays un-fired is the dodge this prevents (memory is supplement only, per the memory-only-insufficient rule).
For changed upstream owners, check-ccl-skills.sh (via scripts/impact-chain-gate.rb) is the mechanical closeout over every added source-register row; the declaration format (behavioral-evidence / observed-failure / firing-path fragments), anchor rules, wording-only classification, the RED-baseline floor, and the author-declaration trust model: references/external-practice-controls.md#behavioral-evidence-and-attestation.
For shared-skill changes, classify the diff before finalization: shared-skill change is defined in references/dual-track-review-gate.md (it also covers the plugin-shipped command/behavior surfaces outside skills/); wording-only means punctuation, grammar, typo, formatting, or synonym substitution with no change to trigger, scope, routing, validation, condition, example, owner, or acceptance meaning, and touching no frontmatter (any /frontmatter edit, even a pure typo fix, is a routing-surface change, never wording-only); all other changes are non-wording.
This SKILL.md is very large, so SkillsMP previews the first section here.View on GitHub
alias_audit_ok
interim / R0 pending
ccl_skill_check_ok
ccl_skill_check_interim_ok
generic_r0_leak_scan_ok
alias_audit_unavailable
ccl_skill_check_clean_ok
r0_status=private-ok
grep
For category definitions, alias-YAML structure, the false-green guard and fallback/token semantics, known_debt semantics, example-identifier substitution, the generic process-retro profile, and ALIAS_AUDIT_CMD enforcement, read references/r0-leakage-audit.md.
Pre-draft example domain selection (preempts retroactive R0 cleanup cycles): R0 catches identifier leakage at audit time; this rule catches scenario-domain leakage at drafting time — scenario shape (entities + verbs + invariants together) reads as source-shaped to adversarial review even when identifiers are sanitized, so apply BOTH axes. Trigger: pre-selection is REQUIRED whenever the changed unit has an example set — ≥2 new/edited examples across the changed files, OR any multi-line / code-fence example (ONE single-line example may use canonical placeholders Acme*/Foo*/sample* without pre-selection; agents cannot bypass by splitting examples). Record a durable closeout validation row (commit body / source map / per-host scratch, NOT chat-only) naming the selected domains, the rejected source domain abstractly — record THAT a domain was rejected, never WHICH industry — and the changed examples checked. Pre-selection feeds adversarial review, never replaces it — codex/adversarial review stays the R0 safety net. For the worked two-axis example, the neutral-domain selection method (source-artifact-relative, not workspace-wide), the exact row format, and row-accuracy rules, read references/example-domain-preselect.md.
Extraction lifecycle handoff: project-specific provenance NEVER enters the shared skill tree — three phases (WIP in per-host scratch → closed-batch provenance in per-host private alias → shared tree carries only label-based capability rules); the shared-repo history (commit messages, branch names, and the entire MR/PR record) is itself shared tree and names only sanitized labels, never real source artifacts — when unsure a surface is shared, sanitize. Existing in-skill registers with real provenance are known_debt and MUST migrate to the private alias before any new provenance is added. For per-phase content lists, migration workflow, R0 jurisdiction boundary, the shared-history sanitization rule, the generic-methodology (shape-vs-content) carve-out, known_debt grandfather cleanup, and authoring-from-a-plugin-install, read references/extraction-lifecycle-handoff.md.
Name extracted skills and reference files by reusable capability, not by the source artifact, source page, project nickname, migration task, or original UI label. Keep source names only as provenance in source maps or reference metadata.
Preserve provenance during analysis, but strip provenance from executable guidance unless source identity is needed for auditing.
For private or domain-sensitive sources, strip identifiable source names from shared skills, shared source registers, and shared source maps. Keep the duplicate-extraction lookup in a local private alias map outside the shared skill tree, mapping original source names to sanitized capability labels.
Renaming a source-derived skill or reference is not complete until the executable wording is generalized too. Search for old source names, old scenario labels, and old capability labels; update them to the new reusable concept or keep them only in explicit provenance.
Do not preserve long verbatim source text in skills. Keep structured summaries, short necessary excerpts, and source status instead of copied dumps.
Reject hindsight causes ("agent careless" / "need more attention" / "should have known"): ask why the action made sense given what the agent could see, not what it should have done. Full method, category prompts, stopping points, and sources: references/source-to-skill-extraction.md (Deep RCA For Extraction).
"The agent did not apply the existing rule" / "application or discipline gap" / "I'll be more careful / will remember / save a personal memory" are the SAME non-cause in disguise — they sound specific but still name the human's diligence, not the missing mechanism, and they license a memory-only / no-shared-change landing. When the cause is "a rule existed but did not fire", that is NOT the root cause: the next why is "why did nothing make the existing rule fire", and the controllable prevention is the firing mechanism — a trigger, closeout gate, validator, or merged clause landed in the owning shared skill so the next agent/project is caught mechanically. A 5-Why that bottoms out at human discipline (try harder / remember / personal note) is unfinished.
Task-retrospective extraction must inspect the whole delivery chain, not only the final fix. For incidents, regressions, contract drift, weak UI, missed tests, bad reviews, or repeated user corrections, trace the failure through definition, implementation, verification, review/MR or release readiness, and retrospective quality. If the root cause includes this extraction workflow allowing a shallow summary, update this skill or its references before claiming the lesson is landed.
A retrospective over a LARGE multi-batch / multi-phase session has a second axis beyond the per-delivery chain: distinct lesson-TYPE axes that must each be covered or explicitly marked no-new-lesson — (a) per-artifact CONTENT lessons (the specific bug / contract value / domain rule; for research/writing/design programs this axis is the METHOD/CRAFT — how the work was done well), (b) PROGRAM/PROCESS lessons (how the multi-batch effort was structured and driven), (c) WORKFLOW/META lessons (did the retro or extraction itself recur shallow, under-trigger, or stop at the most salient content lesson), and (d) SUSTAIN lessons (what went RIGHT and how the next run reuses it — counts only with mechanism + non-luck evidence + owner routing; axes (a)-craft and (d) read from the produced-artifact class — an enumeration driven by correction turns cannot reach them and will come back falsely empty). Landing only the loudest content lesson and declaring the session "fully summarized / 复盘完成" is incomplete. "LARGE" is not a vibe — it fires when the session already carries a coverage/program structure: a source register or named batch-progress standard was applied, OR the work spanned multiple explicit phases/batches/verticals. A user re-ask after a "done" claim = same-scope correction signal — classify first; never manufacture a lesson. Per-axis detail, re-ask classification, DO-CONFIRM card, covered-through watermark: references/source-to-skill-extraction.md (Task Retrospective Extraction).
A long operational delivery session also needs a separate non-lesson delivery-state axis (in addition to the content/program/meta lesson axes above). When the session changed operational delivery state across multiple repositories, branches, MRs, pipelines, releases, or deployable artifacts, the source register must carry that axis — changed artifact set, branch/worktree state, remote/MR state, CI or local verification state, cancelled/retried pipeline state, unresolved risks, and the next concrete action — before "whole-session retro complete" is claimed; closeout records either the axis rows' locator (sanitized labels in the shared landing, real per-repo evidence in scratch/private archive) or artifact/status axis: not-applicable with a reason. If required rows are absent, the retro can be reported only as interim, even when the extracted lesson text is correct. The row-family fields and closeout-evidence forms: references/source-to-skill-extraction.md (Task Retrospective Extraction).
A blocked verification item is not closed by naming the blockage. Before marking a test, device, browser, service, credential, or environment layer unavailable, attempt the normal remediation path for that layer — restart the client daemon, run the documented fallback (full rung list and sandbox-denial triage: the next ladder). Only record unavailable after remediation fails, with command evidence, residual risk, and the next concrete unblock action.
A landed CONCLUSION is a hypothesis until an operation that could have falsified it has been run — both a claim that a tool / capability / lane is unavailable, impossible, or must permanently fail-closed ("fail-closed is the safe default" does not waive the in-env attempt) and a DIAGNOSIS of why an observed failure happened — a search hit proves the text EXISTS, not that it RAN on the path that failed, so run the falsifying operation first — exercise the suspected mechanism on the failing path for an observation only IT predicts, or build a paired control differing in exactly ONE variable — only within existing sandbox/permission, non-destructive, synthetic-target, and credential-safety boundaries (never unsafe mutation, prod/live credentials, secret-bearing state, or a permission-boundary bypass — trading this rule for the security/authority/data-loss axis). Where no safe attempt is available after remediation the record is pending with remediation and residual risk — never unavailable, fail-closed, or a stated cause — and an unfalsified cause is hypothesis, kept off shared surfaces, because withdrawing a landed cause costs more than testing it. When REVIEWING a change that asserts impossibility/unavailability or rests on a diagnosis, independently run the same falsification attempt before accepting it — an inherited "it can't be done" or "this is why it broke" is hypothesis-grade (see the named-convention primary-source re-verify rule). Both forms and failure shapes: references/validation-and-landing.md (Behavioral Validation).
A blocked source read is not closed by naming the blockage. If Figma, code, document, API, or repository reads time out, return partial output, or fail transport, switch to a smaller or different read strategy before extracting rules — and when the source is missing rather than unreadable, change WHERE you enumerate instead. Both ladders: references/source-to-skill-extraction.md#blocked-verification-and-source-read-remediation. Failed or timed-out reads do not count as coverage.
Large reads can lose the middle with no reliable signal — the trigger is read-OUTPUT size, so chunk proactively. A read whose OUTPUT exceeds ~256 lines / ~10 KiB can be silently head+tail truncated (no marker guaranteed), so a single cat/whole-file read does not count as coverage even when it returns no error. Whenever you need a complete view — whole-file coverage, a no-findings/absence claim, or a load-bearing section read — chunk it under both ~200 lines AND ~8 KiB and confirm a mid-file section was ingested. Detail: references/source-to-skill-extraction.md#read-in-chunks-large-reads-lose-the-middle.
Think across the full delivery lifecycle before editing: product intent, design/UX, implementation, debugging, test strategy, launch acceptance, iteration feedback, team onboarding, and normal users without source access. A rule that improves only one slice while leaving another slice ambiguous is incomplete or belongs in a narrower skill.
Evidence must come before new rules. Do not add a new conceptual layer, workflow gate, or strong claim first and then backfill supporting sources. If a useful rule appears before source review, keep it as a working hypothesis and do not land it until evidence confirms it, narrows it, or routes it elsewhere. For subjective design, UX, frontend/client, product, architecture, or review rules, unverified external expertise is not enough to land executable guidance.
Product-agnostic / industry-practice skills require an external authoritative source class in the evidence plan, not internal corpus alone. An extraction sourced only from one internal corpus (an SOP, one repo, one project doc) shows what this org does, not whether the skill matches the public state of the art.
The trigger is a public-best-practice / state-of-the-art claim (architecture, testing-strategy, LLM/inference, observability, release, security, design), not every rule: a rule that encodes an internal-only operating constraint or a postmortem-derived guard, stated with explicit internal scope and no state-of-art claim, does not need external grounding. For rules that do claim to represent industry practice, the charter's evidence plan MUST include authoritative external sources (standards, canonical vendor/tool docs, widely-cited literature, or ≥2 independent practitioner sources) used to confirm, refine, or contradict each such rule — or record per-rule why external grounding is not applicable. Verify any named attribution per the attribution rule; generic established terms (e.g. a well-known named problem or method confirmed by ≥2 independent sources) may be used without person-attribution. Failure shape 见 references/external-practice-controls.md。
Implementing or depending on a named external convention/spec/format verifies it against the primary source FIRST — before building, not after. This fires on implementing the named thing itself — a convention/spec/standard/file-format/protocol such as AGENTS.md/CODEOWNERS placement, an RFC, a wire or file format, or a tool's config contract — even with no best-practice claim (distinct from the industry-practice trigger above, which fires on a state-of-the-art claim). A prior agent's or a prior commit's reading of that convention is hypothesis-grade: re-verify against the primary source before extending it, because a fix-forward built on an inherited interpretation propagates the original error. When the convention uses a term with stack-specific meanings (e.g. "package" = a manifest-bearing directory in npm but every directory in Go; likewise module/project/workspace), map it to each concrete target stack before encoding scope. Failure shape 见 references/external-practice-controls.md。
Match evidence claims to evidence depth. "Full", "complete", "all", "re-read", and "source inventory" claims require named source categories, inspected artifacts, and concrete observations. Use "targeted check" or "no new source read" when that is the real coverage.
A curated digest is one source class, not the repo — its exhaustion is not the repo's exhaustion (digest-masks-corpus trap). A high-quality maintainer digest (AGENTS.md/CLAUDE.md, README, CONTRIBUTING, architecture/design doc) that summarizes a larger code corpus is a distinct source class from the code; a strong digest masks how much went unread. Gates: (1) an "exhausted / complete / no-gap / fully-extracted" claim requires the code corpus as its own register row with a terminal status (deep-read, inventory+owner-mapping, or a downscope citing an actual user instruction — not self-declared); until then scope the claim ("digest-layer covered; code corpus pending") — the sweep is usually inventory+owner-mapping+novelty-spot depth and commonly low-yield, so record that outcome, don't skip the row. (2) Enumerate the source's OWN top-level structure before any exhausted claim — a doc's ##/### sections, a repo's top-level dirs (or the next unit: TOC/pages/anchors/line-chunks for a doc; package/module/test/script/config for a repo) — and mark each read/skipped; un-enumerated structure = unsupported claim (the trap recurs even within one artifact).
The invariant under both shapes is an exhaustion claim must be scoped to a unit you actually enumerated — for the digest/corpus shape that unit is the artifact's own structure; the rule keeps its digest-masks-corpus name for continuity, so do not skip it just because no digest is present. When the claim is over an ACQUISITION CHANNEL SET rather than one artifact ("the public sources are mined out", "there is no more data"), walking a seed list of channel classes is the cheap way to catch a class you never considered — but a seed list is not a universe, so the honest output is which classes you walked and with what search boundary, never an exhaustion claim; the tell that this is the live shape is that each pushback surfaces a class you had not considered rather than another artifact in a known class. Closure and downgrade stay with whatever coverage gate the owning skill already has — do not introduce a parallel status vocabulary here (variant (c) in references/coverage-exhaustion-traps.md).
(3) Four variants share the same enumerate-the-real-artifact fix. (a) self-retrospective (digest = your OWN summaries/MR-descriptions/project-memory, a lossy digest of the change set) → enumerate the actual change artifacts (commit list, diffs, touched files); a project-memory fact ≠ a lesson promoted to the owning shared skill; (b) benchmark / no-gap ("we already cover this" is itself a coverage claim) → read the source's load-bearing decision surface (decision rules, claim-vs-ground-truth checks, data-loss guards — the code, or the full rule text where the load-bearing artifact is executable prose like a SKILL.md/spec), not its advertising overview/feature-docs. (a0) produced-artifact + next-run-delta — a source that produced runnable artifacts owes BOTH the produced-artifacts register row family (under the existing statuses read/deep-read/excluded/routed — "project-specific only" recorded as the reason on an excluded row, never a new status) AND a next-run delta row (what this run's cost went to; what the next run must do, in what order), and attaching the artifacts to a deliverable or archiving them in the project is NOT landed; (4) the verdict owes a per-item disposition row EVEN WHEN THE ROUND LANDS NOTHING — load-bearing surface actually read, owning artifact or route, mechanical firing path for covered; a quick/light/sweep/triage framing does NOT waive the load-bearing read; the row lands on a concrete surface (the final response OR persistent scratch/source-register), never chat-ephemeral; a repeated 深度分析了么 / did-you-deep-read is the recurrence signal — treat it as a validation-gate defect. Gate detail and worked failure shapes (50KB-digest "exhausted" / multi-repo "fully summarized" / benchmark "already covered"): references/coverage-exhaustion-traps.md.
For repository evidence, do not conclude a source is empty or unavailable from the checked-out default branch alone. If the default branch only contains a template, README, or obvious placeholder, inspect local and remote branches, tags, and git ls-tree/git show for candidate feature/dev branches before marking the source unavailable or routing around it.
When the user asks for full, complete, deep, final, whole-codebase, all-Figma, all-docs, or broad extraction for a task, workflow, product, source set, or multi-skill suite, representative sampling is not an acceptable substitute. Build a source register first, define the minimum read depth for each source class, and do not land a final/complete claim until the register is closed or explicitly downscoped by the user.
Conflicts require a keep/merge/discard decision. Do not append incompatible rules side by side.
Never fabricate evidence, source links, quotes, validation output, or install status to satisfy a gate. Record the gap honestly and state what would close it.
LLM consultation output is hypothesis-grade evidence, not verdict (asymmetric corollary to the dual-track gate). When the agent invokes any LLM tool during extraction — codex consult / review / challenge, claude -p, Gemini, an in-process model call, or paste-into-another-chat — the returned text is hypothesis-grade evidence requiring independent verification, identical to a self-generated draft.
This applies in BOTH directions: (a) when the LLM tool finds a problem (a "P0 here" / "this claim is wrong" finding), apply the existing rule (treat challenge findings as valid until specifically verified or refuted); (b) when the LLM tool supports the draft ("all 10 verified accurate" / "no P0 found" / "looks correct"), the support is NOT sufficient validation on its own — confident agreement from a sibling LLM does not raise the draft's evidence grade. The supporting case is the easier-to-miss failure mode: an agent that sees "codex says it's correct" is more likely to ship without primary-source verification than an agent that sees "codex says it's wrong" (the latter forces re-engagement).
Required discipline: every load-bearing factual claim, attribution, version number, API surface detail, or operational recipe in the diff that is external or source-derived and traces only to "an LLM said so" must have at least one non-LLM primary-source verification (WebFetch on the docs page, live --help, the actual repository file inspected directly, etc) recorded in provenance before closeout. Repo-local claims directly verifiable by reading inspected local files are exempt — the gate scopes to external facts and source-derived claims, not to obvious local edits. (The dual-track gate is the challenge-finding half of this rule; the supporting-finding half is here.)
Verify named attribution before drafting from memory — memory-grade attribution is not evidence; author/method pairings ("X 提出 Y", "X is known for Y", "X cheatsheet/heuristic") drafted from recollection have a high error rate. Trigger: any claim naming origin, chronology, standard version, authority, or named methodology lineage — including implicit forms (section/header placement, "based on X-style", see also lists, uncaptioned block quotes, single-author ref links; cannot be bypassed by moving to a header/bibliography). Generic framing ("业内常用" / "industry practice") is acceptable ONLY when the guidance stands without any authority claim. An unverified pairing is recorded as attribution pending (blocks the complete/final claim) until resolved — verify, downgrade by removing the authority, or finalize interim. For the source-quality bar, the full implicit-attribution surface list, the failure shapes, and the pending-row resolution paths, read references/attribution-verification.md.
Routing-surface change gate: any change touching a routing surface MUST pass the Tier-1 static routing analyzer (make eval-routing; also wired into check-ccl-skills.sh) with zero blocking findings before landing. Routing surfaces = a SKILL.md frontmatter description (incl. Use when / Proactively invoke / Skip when / redirects), references/source-register.md, the eval task-bank, or the eval runner/checker scripts.
Blocking = dangling backticked redirect (target not an installed skill), or an exact trigger collision claimed by ≥2 skills with no mutual skip disambiguation.
Advisory (report, never block) = fuzzy collision / possible-dangling bare redirect.
Body-only, typo, or non-routing reference/doc edits run only the existing structural validation, not the routing gate as a landing blocker.
For the analyzer contract, finding classes, blocking-vs-advisory policy, and the staged Tier-2/Tier-3 plan, read references/eval-routing.md.
Routing-surface fixes must cover the coordinator-vs-executor axis, not only the executor. When a routing miss is fixed by editing a skill's description/trigger surface so a request auto-surfaces the right skill, the owner-generalization map MUST ask whether a lifecycle-COORDINATOR/router owner (e.g. product-rd-workflow) also needs the trigger — not only the stack/EXECUTOR owner (*-dev / *-architecture / a single domain skill).
A fix that advertises the request type only on the executor's description is incomplete: multi-stage deliveries of that type (spec → plan → test-first → impl → verify) keep auto-routing to the executor and skip the coordinator's lifecycle gates.
The failure shape that triggers this rule: adding a trigger word (e.g. "重构"/refactor) to stack *-dev/*-architecture descriptions while the coordinator workflow's description never advertises it, even though the coordinator's BODY already claims ownership — a body↔routing-surface contradiction.
Required check before landing any description/trigger edit: (a) does the coordinator's description advertise this request type with a scale qualifier (narrow/single-file → executor; multi-stage/cross-cutting → coordinator)? (b) is there a body↔description contradiction where the body claims ownership the routing surface omits? (c) when the description paraphrases a body trigger / skip-condition that has multiple clauses with different scopes (e.g. clause 1 fires on any edit of a surface, clause 2 only on a semantics change), preserve each clause's scope separately — collapsing a multi-scope trigger to its most salient clause silently over- or under-fires; the body trigger is the primary source, so re-read every clause (the first reading is hypothesis-grade) before asserting the description over/under-covers it OR rewording it. Resolve all, or record per-owner why the coordinator is unchanged.
Validation gate: a repeated routing miss of the same request type across two rounds is evidence the prior fix only patched the executor surface — re-run this coordinator check before claiming the routing class is closed.
Routing-trigger fixes must cover the utterance-variant axis, not only the canonical phrasing. When fixing a routing miss by adding a trigger to a description, the same delivery type arrives under many utterances — the canonical name PLUS restart/redo/from-scratch/continue variants (e.g. a refactor delivery arrives as "重构 X" but also "重新开发", "完全重新开始", "推倒重来", "清除代码重新开发", "redo/rewrite from scratch"); advertising only the canonical phrase leaves the variants unmatched, so the workflow silently fails to auto-trigger on them. "The rule/trigger exists but the utterance class is uncovered" is a validation-gate defect: enumerate the restart/redo/continue variants of the request type and add the high-value ones (within the 800-char cap; route overflow to the body entry-precedence text). A repeated miss of the SAME delivery type arriving via a different utterance across rounds is the signal this axis was skipped.
In Claude Code, before fixing a routing miss with a trigger-word edit, check whether the skill's description was even IN the host listing — it may be budget-dropped. A name-only entry silently voids a keyword-based routing fix (the skill stays reachable by explicit /skill-name). Evidence bar (do not over-apply this as a catch-all): conclude budget-dropped only from concrete evidence — this turn's listing shows that skill as name-only, /doctor output, or other host-listing proof; absent that, treat it as a hypothesis and STILL do the normal trigger / utterance-variant / coordinator fix (this rule does not replace them; a visible description misjudged as name-only is the reverse trap). Corollaries: (a) a routing/bootstrap doc assuming "every description is always visible" is wrong under budget pressure and must not be a low-traffic gate skill's sole discovery path; (b) on non-Claude-Code hosts verify the host's own listing behavior from its primary docs — any LLM's "it's a host bug" guess is hypothesis-grade until so checked. The budget mechanism, the cold-start trap, and the remediation levers: references/skill-listing-budget.md.
A deep review / benchmark of the skill repo is an extraction once it produces durable skill-change findings. Reviewing or auditing the ccl-skills repo — especially benchmarking it against external/reference skill packs (superpowers / gstack / etc) — becomes an extraction the moment the output is meant to change reusable skill behavior (a target-output map, a gap list, or a remediation plan). Invoke skill-extraction-workflow and set the charter BEFORE the first findings/gap-report turn, not after accumulating findings.
Boundary (avoid over-fire): a casual "看一下 / 这写得怎么样", a one-off opinion, or a pure code/doc PR review stays ordinary review; it becomes extraction once the output is meant to change reusable skill behavior.
A multi-turn review that lands a change-plan without an upfront extraction charter is interim — rebuild charter + target-output map and pass the dual-track before claiming landed.
The benchmarked external packs are reference-only: route a missing method/tool-layer capability to that pack; only land a ccl-layer rule (domain/governance/cross-cutting) here, never a copy of the external skill. Verdicts: P/I/M/W, grep-anchored; M needs the functional-equivalent check.
Treat remembered tool, script, installed-skill, repo-root, validator, and executable paths as stale until re-resolved in the current workspace. A path from memory, a prior-round plan, a compacted summary, shell history, handoff notes, or another agent's report must first be re-resolved against the current workspace (reopen the owning skill/reference or inspect the current repository), then probed for existence and executability before running it or reporting it missing. Prefer repo-local or skill-relative scripts only when they resolve inside the loaded skill package or trusted ccl-skills repository root, pass containment and no-symlink/hardlink trust checks, and are not merely same-named scripts in an arbitrary product repo or fork; otherwise fall back to a trusted installed-skill path or manual checklist. If the remembered path fails but a current-context trusted path succeeds, record the failed path source, fallback probe, resolved path class, trust check, and whether shared-file content validation was affected; do not classify shared skill content as broken only because a stale tool path failed.
Prefer updating the smallest existing skill over creating a new one unless the trigger, owner, and workflow are clearly different; different runtime tools, release gates, or verification surfaces are evidence that the workflow may be different enough to split.
Impact-chain: a decision-surface edit must map BOTH directions. When the changed skill owns or executes an upstream decision surface (architecture, design, product workflow, testing strategy, release, observability, security), the map must span the whole chain: an implementation/dev edit checks the upstream owner (architecture for cross-boundary semantics, service boundaries, contracts, storage ownership, shared-package decisions; design for UI/UX judgment; testing-strategy for layer selection; product-rd-workflow for cross-stage gates), and an upstream-owner edit checks the downstream executable owners (implementation, client/runtime, test-case/test-mechanics, release/runbook, and the review gates that make the rule real). "Architecture/design owns X" without the concrete rule the downstream skill must apply is incomplete — a dev-only fix is incomplete when the root cause includes who owns the decision/exception/migration/acceptance gate — and an upstream-only fix is incomplete when future agents still lack concrete coding/testing/verification instructions. For upstream-owner changes this is the durable impact-chain map stored in references/source-register.md (upstream rule | downstream owner | expected executable behavior | status(updated/unchanged/routed/not-applicable) | evidence; empty template rows, header-only tables, or free-text paragraphs count as absent); it must include at least the directly affected implementation skill(s), testing/review owner, and product-workflow owner unless each is explicitly not-applicable with a reason. scripts/check-ccl-skills.sh machine-enforces it for the curated upstream-owner list plus *-architecture and platform-* entrypoints and MUST block merge when no non-empty source-register row exists; when you add or reclassify an upstream-owner skill, update that script list in the same PR or record why it is outside the automated gate.
Stack-specific edits need a sibling-generalization mini-map before editing (source stack, sibling stacks, shared workflow owner, per-sibling update / unchanged / route-to-shared, and reason). A lesson from one service stack may be generic backend practice that also belongs in a sibling (e.g. a Go-service lesson that is generic also belongs in the Python-service skill); land a language-agnostic rule in the smallest common workflow/testing/architecture skill, and record why a sibling was left unchanged when the rule is genuinely stack-specific. Missing this mini-map is a process failure even if a broader map is later reconstructed; the work is not complete until the durable source map names the mini-map decisions plus any upstream/downstream owner-chain checks (per the anchor rule, a passing static script does not prove these gates ran).
Owner-generalization map must include installed external skill packages, not only ccl-internal skills.
When the agent's current session's available-skills list contains additional installed packages (e.g. process-discipline skill families like superpowers:*, concrete-tooling families like gstack-*, vendor-provided skill packs, or any other third-party skills shown in this session's list), each lifecycle stage in the owner map MUST also consider those packages as plausible canonical owners.
The recurring failure shape: extracting content into a CCL skill that duplicates an installed external skill (a "shipping" section in product-rd-workflow that re-implements what gstack-ship already does; a "brainstorm before code" rule that re-implements superpowers:brainstorming), forking the discipline across two surfaces and creating silent drift.
Method: scan the current session's available-skills list before building the owner-generalization map; for each lifecycle stage, name the external-skill candidate alongside the ccl-skill candidate; route to the external skill when it owns the operational recipe and keep the CCL skill as the gate-keeper / cross-cutting rule layer.
When external packages are absent in a teammate's environment, the CCL skill's principle wording must stand alone (no broken superpowers:* / gstack-* references in executable guidance) — name them as "if installed, route to X; otherwise apply the principle inline".
When a user correction or self-check exposes one missed extraction dimension, sibling owner, or lifecycle stage, scan the immediate neighbors on the same axis before landing the fix. Reuse existing machinery: target-output map for lifecycle, sibling-generalization mini-map for stack/owner, and the source type's dimension enumeration for judgment axes. Do not invent new axes per task and do not walk beyond immediate neighbors. Land only the smallest needed updates and record one line per neighbor as update, unchanged, or routed. The trigger is a discovered miss, not every extraction.
Class-wide routing/trigger changes require COMPLETE-set coverage in one pass — the immediate-neighbor scan above does NOT apply. The neighbor scan covers a single discovered miss; a change whose rule is "every skill of class C should advertise / scope / carry X" is out of its scope.
For such a change, first write an explicit, narrow, source-backed class predicate (from how the user/source phrased the class — not an expansive inference from examples; if the predicate is ambiguous or huge, downscope or ask, and record non-member exclusions).
Then the COMPLETE set matching that predicate is the required coverage: enumerate the installed members from the session available-skills list PLUS any referenced repo-present CCL members (absent ones get install-drift: pending per the next rule, never silent omission), and update or explicitly mark each unchanged/routed in ONE landing before claiming the class closed.
Landing one member-pair and waiting for the user to surface each remaining member across rounds is the defect this prevents; a repeated same-class miss across rounds is the signal; member-JOIN duty: references/source-to-skill-extraction.md#member-join-inheritance.
Validation gate: the closeout map lists every predicate-matching member with a status, or the class is not closed.
(Ordinary single-skill edits still use owner/sibling checks, not a full-class sweep.)
A referenced ccl-owned/vendored skill not installed in a host is install-drift, not a valid not-applicable. When enumeration reaches a skill that exists in the canonical CCL repo (or is vendored here) and is referenced by the tree but not installed in a host, do NOT mark it not-applicable: not installed and move on — that records a symptom as a reason and the skill silently never fires there. Record install-drift: pending, surface the exact remediation, and install it ONLY via an approved user/maintainer instruction or the managed install script — do NOT silently create host symlinks or install unprompted (a host mutation changes future routing globally and can point at the wrong checkout). Until installed, that member's coverage stays interim, not omitted. This applies ONLY to ccl-owned/vendored skills; an absent external/system package routes to maintainer/upstream, never local install/edit.
Any extraction beyond wording-only cleanup also needs a provenance-to-target diff before finalizing. A source register, source map, evidence map, target-output row, or task-retrospective event proves only that a mechanism was seen; completion requires naming the target file and the executable rule, recipe, checklist, or acceptance gate that future users will actually apply. If the target is only provenance text, patch the owning skill/reference, route it elsewhere, or downgrade the claim.
references/uiux-judgment-extraction.md
pending
out of scope
discarded
routed
no-durable-output
Deferred-evidence over-polishing corrections route to product-rd-workflow's DFE-CONT rule: when a delivery keeps hardening tests/verifiers after the real/external evidence was unavailable, blocked, unreachable, deferred, skipped, or mock-substituted, or reports such real evidence as complete, the target-output map must name DFE-CONT (paraphrases like "why keep fixing tests when the cluster wasn't reachable" count — exact deferred/skipped wording is not required). A bare mention of runtime/external access is not enough: a test-hardening, coverage, or test-order correction with no unavailable/blocked/deferred real-evidence element and no deferral-as-terminal claim defaults to testing-strategy; when both a deferral signal and a test-order signal are present, map to both (DFE-CONT + testing-strategy, the test-case-first rule still mandatory). Validate by confirming the DFE-CONT block and its non-completion rule are present in the installed product-rd-workflow skill's SKILL.md (resolve via routing/skill discovery; inside the ccl-skills repo: skills/product-rd-workflow/SKILL.md — the file is not at that relative path on installed hosts), and keep this routing token in sync if that block is renamed.
If a retrospective correction says tests were run before test cases, or asks why test cases were not written first, the target-output map must include testing-strategy and any coordinating workflow such as product-rd-workflow. A final answer without a durable test-case-first prevention rule, validation command, and challenge or explicit no-update reason is only interim.
A reusable lesson must land in a SHARED artifact, and skill-extraction-workflow itself gets a prevention point. Two paths with DIFFERENT strength:
(i) exposure-by-failure-class — when a reusable lesson is exposed by a routing miss, shallow retro, validation gap, wrong-ownership decision, or proxy/subset/slice/local-bound objective narrowing, always land at least one durable prevention point in this workflow itself (naming the failure class, correction path, and validation gate that stops recurrence), even when the concrete lesson also belongs in another skill or project doc — no opt-out; a target-skill-only landing is insufficient.
(ii) explicit-ask — when the user asks whether it was "沉淀到提炼技能" / "放进提炼技能" / "固化到 extraction workflow", the target-output map must include this workflow: either land a real prevention rule here OR state why it is unchanged and name the owning skill that received the rule (a target-skill-only update is insufficient when the failure was that extraction was skipped, shallow, or only oral).
Either way the landing must be a shared artifact — CCL skill, shared reference, validator, checklist, or project template — naming the exact trigger/gate teammates will hit; for a reusable routing/process/team failure, classify a memory-only landing as insufficient — local-only and "I'll remember next time" count the same (local memory supplements user/workspace context only). A candidate that turns out NOT genuinely reusable may be discarded with evidence. When neither path fires, ordinary routed/unchanged disposition to a different owning skill stays available per bullet A step 3.
For any analysis-parse-fix-test-challenge loop, separate five stages explicitly: analysis, parse/decompose, fix, test/verification, and challenge. Add a replay step when validating reusable lessons: rerun the same task shape or a close analog through the proposed workflow and check whether the required outputs and gates still appear in order. Keep four outputs explicit: the project-level fix, the test/verification evidence, the challenge findings, and the reusable workflow lesson. If the same pattern can recur across different domains, lift only the workflow lesson into skill-extraction-workflow; keep domain-specific implementation details in the owning project or target skill. See references/analysis-parse-fix-test-challenge-replay.md for the replay validation runbook.
The agent failing to self-invoke this workflow (the user had to point out that skill-extraction-workflow should have been used) is a tracked failure class that recurs across the session / different tasks, not only within one extraction thread (so the "twice in one extraction thread" scope above does not catch it). Honesty: an in-the-moment self-trigger is recognition-dependent — the always-on bootstrap layer raises its salience but is NOT a mechanical gate; do not overclaim a passive rule "fixes" the recurrence.
One self-detectable firing point does exist and must be used: the moment YOUR OWN output names 沉淀 / 提炼 / 复盘 / "distil this into a skill", OR enumerates what an external source has that we lack (a gap list vs another pack; see references/firing-point-placement.md), that naming is a trigger to RECOGNISE the owner and load it — not a licence to widen scope: shared-skill edits still need the authority you already have, so when the user's request covered only a status review or a narrow fix, record the extraction as pending with the owner named and ask rather than self-authorising a shared-skill change off your own suggestion.
The mechanical backstops are (a) the closeout gate — a committed skill-change with neither a visible in-session skill-extraction-workflow invocation nor the round's durable charter/target-output record is interim (per the closeout gate's evidence forms) — and (b) user-signal escalation: you generally cannot self-count misses you did not notice, so a user-pointed-out under-trigger is a recurrence check (was there a similar miss earlier this session, even on another task?) and, if so, escalates to tightening the always-on discipline rather than landing another narrow per-case trigger.
Firing-point-placement corollary: when the SAME meta-class (a precise gate walked past at the routing → pre-code/design transition) recurs at a new lifecycle sub-point despite prior bootstrap-salience + the closeout gate, the durable lever is moving the owning gate's firing point ONTO the transition itself (pre-substance-draft AND pre-first-impl-edit) and sharpening name→invoke — naming/knowing an owner is NOT invoking/loading it, and a named-but-unloaded owner's mechanical rules never fire — at the SAME transition, NOT another bootstrap/per-case bullet or more prose.
Record-field corollary (the forgery surface): any field that NAMES an owner — a checklist row, a CLI flag, a "decision:" slot — is fillable without invoking that owner, and filling it is what feels like discharging the gate, so it carries an explicit invoke bar on its triggered values.
The self-detect firing point's authority boundary and observed shape, the record-field corollary expansion (the invoke-bar coverage set-diff mechanics, the delegation-dispatch worked case), the worked recurrence-chain, and the landed owner-dispatch implementation: references/firing-point-placement.md.
Run your own adversary to convergence BEFORE any "done / fixed / passing / covered / converged / complete" claim — your own such claim is the least-trustworthy thing you emit. For any non-trivial completion/coverage/convergence claim, you must have already run — yourself, not deferred to the user — the verification or adversarial pass that would catch its failure, to a clean fresh result (a first clean pass on the current candidate, never a "confirm my fix" pass), OR downgrade the claim to interim and name what you ran vs. didn't. "Covered / converged / already handled" is a claim, not a status — back it with firing-path or clean-pass evidence or do not emit it; this self-adversary duty never narrows the mandatory dual-track challenge (it is the always-on generalization of self-audit-to-convergence, not a replacement for the gate).
That pass is a walked enumeration over the properties the candidate asserts, never a re-read: a property whose killing mutation you cannot name was never verified, and re-reading your own prose can only ever confirm that the prose is self-consistent with itself. A mutation you did not APPLY is a hypothesis, not evidence — bound its blast radius (never buy a RED by disabling a guard against a shared or live dependency; where no isolated path exists record the property unverified). Prove the oracle can fail before trusting its clean verdict — point it at something you know is broken and watch it report that; a check that can only ever say clean is no evidence, and whatever you produced while fixing a previous round's findings is part of the current candidate and re-owes the whole enumeration. A failing anchor is first a question about the ANCHOR, not a verdict on the implementation (§Self-audit). A validated oracle is still clean only over the DIMENSIONS it crossed — proving it can fail says nothing about the axis you never varied, so a clean run is reported with the dimensions it covers, and the enumeration walks dimensions (shape / provenance-and-trust / cardinality / semantics / ordering — testing-strategy owns that list) before values. If no contradicting observation exists, the property is unverified and must be labelled that way rather than counted as audited.
A scoped "X verified; Y not run" is an interim checkpoint, notdone/complete/landed: Y not run blocks a done/complete/landed claim unless a risk owner — the user/maintainer, never the agent self-accepting — explicitly accepts the gap AND it is tracked to that owner (agent self-labeling "risk accepted" or "deferred" does not qualify; scoping is a downgrade, never a license to call the narrowed slice done). a user prompting you to keep digging / verify / disputing a "covered/converged/done" is a premature-completion signal — on the such correction in a session (even across different tasks) escalate to tightening this discipline, not just fixing the one case (per the repeated-correction escalation above).
The full self-adversary method — the mutation enumeration, the applied-mutation discipline, the independent-oracle validation, the re-owe-after-fixes rule, the graded-verdict calibration, and the recognition-dependent honesty caveat: §Self-audit.
Automatically trigger durable learning when extraction work exposes a reusable failure — and when ordinary delivery work does, capture it here too, but without extraction taking over the delivery: let the active owner (product-rd-workflow / defect-diagnosis / testing-strategy / …) handle the immediate work first, then route the durable lesson here. For a premature-stop correction after affirmative continuation, immediate recovery means first rerun the active owner's current continuation/blocking gate in full (for product R&D, Pre-Final Continuation Gate steps 1–6) against current state, then follow its observable outcome — proceeding only when a literal binding exists (the original proposed-next action/scope plus literal assent, preserved in the visible conversation or quoted exactly in trusted host-owned session/compaction state — never reconstructed, broadened, or substituted — or the user's correction literally naming the paused action and scope) — a semantic compaction paraphrase or a bare "why did you stop" complaint is not path-(b) authority, and a blocked: recovery without the step-1 evidence and a specific missing authority/ambiguity is invalid — asking again when neither binds, the user intervened, or scope/gates changed, and never copying real conversation text into a shared repository record. Do not let correction RCA or extraction extend a still-authorized delivery, and do not let stale assent bypass a newly pending or inconclusive gate. After delivery recovery, correction RCA plus the durable prevention landing and verification are still due before the turn can be reported complete; otherwise report interim. The full binding rules, the continuing:-line form, and the invalid-blocked:-recovery rule: references/resume-paused-delivery.md.
The trigger is a correction about reusable skill/process behavior, NOT every bug/QA/review nit handled inside its own owner skill. Do not wait for the user to say "沉淀": if the user points out a missed source, missed sibling skill, shallow rule, overclaim, domain leakage, missing trigger, missing verification, repeated correction, or that this workflow should have been invoked at all (an under-trigger / "should you have used 提炼/复盘" correction, including outside an active extraction), run correction RCA, update the smallest owning skill/reference/validator, and verify the prevention point before finalizing the turn.
When the user asks whether a lesson was durably landed after a failed extraction, verify the actual skill diff or file content first. Do not answer from memory or intent. If the prevention rule is not present in the owning skill, add it or state that it has not been durably landed.
Consolidate and retire rules; a skill's rule set must not grow monotonically. Every correction adds a guard, but an N-bullet wall on one theme is itself the over-prescription/unreadability failure, and "just append another bullet" is how it regrows.
Prose rules compete for a finite attention budget, and joint satisfaction degrades with the number of constraints. (Predecessor claim — only the most-salient rule applies, the rest dormant — withdrawn, unsupported.) Descriptive, not permissive: attention limits never excuse a violated rule, and are not a reason to refuse a needed one. (a) Merge-into-canonical beats append: appending adds contradiction surface and spends budget. (b) Do not rely on co-resident prose for requirements that must hold JOINTLY — structure them as a walked enumeration at their firing point: walking a finite list works where holding a conjunction does not. It is why "the rule was loaded" never predicts "the rule was applied". Detail: references/external-practice-controls.md#instruction-following-mechanisms.
A rule's TEXT in a SKILL.md/reference is living — merged, tightened, or retired in place — unlike the source-register.md ledger (append-only + supersede-by-pointer; never edit/delete a row). "Land a durable prevention point" (per the always-land rule) is satisfied by a merge into an existing canonical rule, a validator/checklist gate, or a reference pointer — NOT necessarily a new top-level bullet: before appending a rule, grep the section for an existing owner of the same failure-class and merge instead (this extends the keep/merge/discard conflict rule from incompatible to redundant rules). A consolidation that rewrites or retires rule text is a non-wording shared-skill change whose behavioral-evidence row (semantic-control) MUST carry a zero-loss obligation map — every before-obligation maps to surviving or genuinely-subsumed text, none silently dropped; the challenge inspects that map. Dropping a real guard under the banner of "consolidation" is a regression.
Wording-level dedup mechanics route to tighten-doc; the at-add-time consolidation check, the form-by-failure drafting table, the obligation-table format (incl. the verifiable-survivor-pointer rule), the package/support-file integrity axis, strict "subsumed" criteria, register-row boundary, and audit recovery: references/rule-consolidation.md.
description
Every shared-skill change, including wording-only edits, must include a recorded independent review row before commit.
Non-wording shared-skill changes must also include a recorded challenge row AND a recorded behavioral-evidence row before commit (actual behavior/routing deltas require a true RED-baseline; unchanged controls use paired semantic-control; status rules in references/dual-track-review-gate.md). A non-wording owner package must include at least one RED-baseline row, so stable-control labels cannot self-clear the package. For a DESTRUCTIVE/irreversible change, a RED-baseline row must show the protected predicates were mutated, not merely that negative cases ran. Executing the must-NOT-touch cases is necessary but not sufficient: a negative probe that would still pass with its protecting predicate removed is evidence of nothing (recurring shape: a degenerate fixture short-circuits every probe on an unrelated conservative branch, so the safety predicate is never reached and the green suite certifies the hole).
So the row records, per protected predicate, the removal that was applied and observed to turn the suite RED for the right reason — a bare non-zero exit does not qualify (a mutant that breaks syntax or fixture setup also exits non-zero and would bank a broken build as proof of sensitivity); the failure must be attributable to the named protected assertion, and attribution is differential (the owning assertion passes in the unmutated control and fails under the mutant, with no non-owning assertion failing) rather than a substring match on aggregate output. An unapplied "this mutation would fail it" is a hypothesis. testing-strategy owns the encoded form of that walk (route, don't copy) — for a destructive artifact the walk belongs inside the suite so a later fixture change cannot silently re-blind it.
A challenge skip row is allowed only for wording-only changes; trivial scope does NOT exempt a non-wording change, and ANY skill description/frontmatter edit — including a pure typo fix — is NOT wording-only (it changes the routing surface) — both require the full gate.
If a human explicitly asks to skip independent review or challenge, record the review state and residual risk honestly instead of fabricating a pass. Chat or candidate-local text may authorize an in-scope preparation/commit action, but CI authority comes from the protected platform. Distinguish a narrow exact-candidate review_waiver (only the review lane becomes non-blocking) from an exact-candidate merge_authorization (the human's final merge decision: every CI lane remains visible but none may block that merge). Neither state rewrites failures as passed.
code-review permits one review plus four challenges. Non-wording Agent-autonomous work MUST use scripts/extraction_review_gate.sh at challenge_budget=1 (2 rounds); proven wording-only work keeps the single-review path and no terminal ledger. Later human-requested review is separately attributed outside the non-wording chain, never relabelled new rounds. Neither budget limits deep self-review, implementation, tests, or authenticated human action. self_review_gate fires before external review, after findings/candidate/scope changes, at post-budget, and before an Agent completion claim; it blocks only another review/completion claim, not productive work or human merge authority. Candidate input cannot assert human authority.
Agents cannot self-authorize skipping independent review for any shared-skill change, a challenge skip for non-wording shared-skill changes, or skipping the behavioral-evidence row / true baseline comparison for any change that alters behavior or routing.
Missing, skipped, inconclusive, or unavailable required review blocks Agent completion/commit; remediate within wrapper budget or use an approved alternate under the same scope, attribution, timeout, and output checks. If all lanes stay inconclusive, report interim. At budget end validate the v3 receipt-bound ledger: it derives state from the supplied controller chain but cannot prove omitted history or live remote currency, so retain history and run the reference's landing recheck. Report non-success, continue independent work, and park only dependent work. Only an authenticated human may waive review or stop iteration.
