| name | debug-toolkit |
| description | Fires when you observe a defect, bug, unexpected behavior, or symptom; when you start a debugging task; before forming a root-cause hypothesis from a symptom; or when consulting known thinking patterns (Patterns). |
Debug Toolkit — A Workshop of Thinking Patterns
This skill is NOT a catalog of off-the-shelf tools.
It is a systematized thinking framework for building tools yourself.
When the symptom is not on the menu, do not force-fit it to the closest pattern.
If you don't have the right tool, build one. That is the spirit of this skill.
0. The Minor-Marque Mechanic Mindset (Preface)
This skill is a toolbox for a mechanic who services minor / less-popular marques of cars.
Generic tools — off-the-shelf scan tools, OBD-II readers, standard logic analyzers — handle the common failure modes. But this skill does not catalog ready-made tools. In a minor-marque restoration shop, the required tool often does not exist at all. The mechanic invents the tool on the spot.
When you encounter an unfamiliar symptom, you have two choices:
- Force-fit the symptom to an existing tool (heuristic over-fit) — leads to misdiagnosis, symptom-hiding, recurrence, or the problem reappearing somewhere else
- Invent the missing tool yourself (SST = Special Service Tool) — the professionalism of a minor-marque mechanic
This skill systematizes the second mindset. When you see a symptom that is not on the menu, do not force-fit. Invent a new SST when needed. And when you judge that the SST you built can apply to other domains, propose adding it as a new Pattern to this skill (see §4 Self-Extension Rule).
This is a growing thinking framework, open to all CC users as a shared asset. The Pattern you articulate today might rescue a different domain's problem tomorrow.
The "secret sauce" metaphor: this skill is not a recipe. It is the cook's philosophy — what makes flavor good, where to make judgments, how to learn from failures — passed down in the form of a particular shop's tradition. Do not imitate the steps; embody the thinking.
1. How to Use (Onset Workflow and the Hard Interlock)
1-1. Steps at the Start of a Debug Task
When you observe a defect, bug, or unexpected behavior and start debugging:
- Articulate the symptom: describe what is happening as objective fact (no speculation)
- Copy the template: copy
templates/debug-report-template.md to a task-specific path
- Example destination:
_Prompt/02_buildai/_DebugReports/<task-id>/debug-report.md (legacy _Prompt/01_FromBuilderAi/_DebugReports/ also accepted)
- Decide the destination path based on the project's conventions
- Consult the §2 Pattern Catalog: look up which Pattern applies to the symptom. If one applies, use its three-layer structure to form a hypothesis
- If no Pattern applies: invoke the meta-thinking pattern in §3 ("Pattern for Extracting Patterns"). Treat the case as a candidate for a new Pattern
- Fill out debug-report.md while debugging: complete §1–§8 of the template. Section §2 ("Pattern in Use") must be filled from the start, not at the end
1-2. The Hard Interlock (debug-report-gate hook)
This skill includes a completion-time forced check mechanism:
- Hook name:
debug-report-gate (Stop event)
- Script:
~/.claude/hooks/debug-report-gate.sh
- Behavior: when CC tries to declare completion, the hook checks whether all required sections in the in-progress
debug-report-*.md are filled. If any required section is empty, completion is blocked.
This forced mechanism structurally prevents CC from "completing with §6 left empty because we are busy." Documentary rules alone can be ignored by CC, as has been observed in prior cases. Some invariants can only be protected by physical enforcement at the hook layer (see also Pattern 7 in §2).
1-3. About Hook Registration
The hook script ships with this skill. The actual registration in settings.json is performed by the user (human):
- CC cannot edit
settings.json directly (per CLAUDE.md / safety-principles)
- See
templates/hook-registration-guide.md for registration steps
- The hook file can be placed in the prescribed location even before registration; the user registers it during the next maintenance window
1-4. Intended Audience
- CC (Claude Code, the implementing AI): primary reader. Consults the Pattern Catalog and fills the template during a debug session
- Design AI: organizes new Pattern proposals using this skill's format
- OSS users: reference this skill in their own projects and add domain-specific Patterns over time
2. Pattern Catalog (Core)
Less "looking up the menu" and more "opening a drawer of thinking patterns."
Each Pattern is described as a Three-Layer Structure (abstract description → concrete case → lesson + cross-domain reach).
Why three layers: humans (and AIs) cannot understand abstraction without concrete examples,
but concrete examples alone do not generalize. Lesson and cross-domain reach recursively reinforce the abstraction.
Pattern 1: Distinguish "all targets" vs "specific targets" first
Abstract layer:
When observing a defect, the first thing to check is the scope of occurrence in the target population. "All targets affected" vs "only specific targets affected" partition the hypothesis space cleanly. Common infrastructure / rendering / configuration layer vs individual data / state / condition layer. Mixing these leads to attempts to fix a common-layer problem at the per-target data level (or vice versa) and quickly turns into a swamp.
Concrete case:
On a management screen, every registered target (dozens of items) showed "two status badges drawn side by side." On the first item observed, the diagnosis "this target's data is corrupted" was nearly adopted. Then a second item showed the identical symptom, and the cause was identified as a problem in the common list-rendering logic. Had work started from the first item alone, fixing target data would not have removed the symptom.
Lesson:
When you see a symptom, build the habit of immediately comparing one more target. After observing one, always look at a second.
Cross-domain reach:
- In ECU reverse-engineering, "the same communication error on all ECUs" vs "errors only on a specific ECU" point to firmware / protocol issues vs ECU individuality / data variation respectively
- In embedded-device firmware development, "all tags fail to read" vs "only specific tags fail" — reader-side vs tag-side
- In legal-compliance traceability, "missing records across the entire period" vs "missing records only in a specific period" — system fault vs individual operational error
- In engine-control calibration-map generation, "errors across all driving conditions" vs "errors only in specific regions" — global model coefficients vs interpolation-boundary issues
Pattern 2: Flip Descriptive Data into Prescriptive Questions
Abstract layer:
When reading past documents, commit logs, scope-of-investigation tables, or data, do not stop at "this is past fact." Flip it: "why was this information needed?" and "therefore, the design ought to have been ...?". Information that is not written (design rationale, psychological motives, preventive intent) can be recovered only through prescriptive reading. When a table appears, recognize that the existence of the table itself is a mirror reflecting the designer's areas of concern.
Concrete case:
A past instruction document for a project contained a comparison table covering several other related projects. The implementer processed this descriptively, as "reference data on the current state." But asking "why was this table needed?" would have surfaced a design judgment: a preventive motive to avoid breaking compatibility with the other projects. The presence of the table itself was a signal of an unwritten preventive intent. The implementer did not perform this flip and remained unaware of one of the design motives until disclosed later.
Lesson:
When a table appears, think one line about "why this table was needed" before moving on. The breadth of investigation scope reflects the designer's areas of concern. When a design choice favors "single management," "unification," or "minimal configuration," the explicit "cost avoidance" often hides an implicit "ripple-effect avoidance" preventive motive.
Cross-domain reach:
- In legal-compliance traceability, when reading past communication histories, "what is NOT written" hints at the truth. Silence is testimony
- In engine control, reverse-deriving an intended torque map from a fuel map is similar — the shape of the map reveals the controller's intent
- In ECU reverse-engineering, the layout of calibration data shows which parameters the developer wanted to tune
- In RAG-system development for conversational AI, what the user did NOT ask hints at premises the user already takes for granted
- In organizational meeting minutes, topics that did NOT come up reveal the organization's blind spots
Pattern 3: The Trap of Judging a Specific Target by a Source Common to All Targets
Abstract layer:
When designing judgment logic, first verify whether each input source is specific to the judgment target or common to all targets. Sources common to all targets must NOT be used as judgment material for a specific target. Common-source-based individual judgment yields the same result for every target — a logical contradiction. Enumerate input sources and label each as "target-specific" or "common to all" before designing.
Concrete case:
In a project-classification system designed to "judge the configuration of a target project," global settings (common across all projects) were included in the judgment material. In production, "multiple projects all collapse into the same judgment result" was observed. One subset of the common configuration (settings.json) was already documented as out-of-scope for judgment, but other subsets in the same common configuration (hooks/skills/rules) remained in-scope. Logical consistency was broken. The fix excluded the common source completely, judging only target-specific sources.
Lesson:
At judgment-logic design time, label every input source as target-specific / common. Common sources are out-of-scope for judgment. A design that excludes only a partial subset of a common source is logically half-baked and will inevitably break.
Cross-domain reach:
- In ML feature engineering, a feature that is constant across all samples cannot improve classification performance (information-theoretically zero)
- In engine control, using a coefficient common to all engines as a per-engine correction value defeats individual-variation compensation
- In organizational HR evaluation, using criteria common to all employees (e.g., the company mission) as the basis for individual evaluation produces uniform ratings
- In ECU reverse-engineering, reading the Vehicle ID region (common to all ECUs) reveals nothing about the individual ECU's character
Pattern 4: Multi-Layer Safety for Catastrophic Operations
Abstract layer:
When implementing irreversible operations (delete, overwrite, external API call, flash write), a confirmation dialog alone is insufficient. The invariant "this function does not perform irreversible operations" must be structurally guaranteed across code layer, type layer, test layer, and UI layer. The same professional culture as a mechanic who, when working on the brake system, always disconnects the battery and verifies master-cylinder protection. Multi-layering is the only way to protect assets from cognitive bias in humans (and LLMs).
Concrete case:
A management tool's "remove from list only — do not delete the actual file" function. Failure of this contract would be a critical incident — the user's important data deleted. The design split responsibility: a "file-delete function" and a "list-management function" as separate functions, with the list-removal feature only calling the latter. A yellow warning ("This does NOT delete files") was displayed in the UI. Ideally, a unit test would assert "after list-removal, the directory still exists," but that test remained unimplemented (see Pattern 7). At the implementation-pattern level, the three-layer defense (responsibility-split + UI warning + function naming) was in place.
Lesson:
Do not put irreversible and reversible operations in the same function (responsibility split). Do not include delete / rm in the function name (it invites mistaken calls). Display explicit warnings in the UI. Then, guarantee the invariant with tests (see Pattern 7). Only when all of these are in place can it be called "multi-layered."
Cross-domain reach:
- In legal-compliance traceability, "permanently delete from archive" and "remove from active view" must be separate functions
- In embedded-device firmware, flash write and RAM write absolutely must not share the same function. Flash is irreversible in both lifetime and content
- In ECU reverse-engineering, an EEPROM-rewrite tool should separate read mode and write mode at the hardware level. Software-layer confirmation alone is insufficient
- In ISO 26262 functional safety, an irreversible operation at ASIL-D level (e.g., releasing ABS braking) must be protected by a multi-channel control system. A confirmation dialog alone does not satisfy ASIL-B or higher
- For smart-contract reentrancy protection, doubling up on checks-effects-interactions and a mutex prevents recurrence of The DAO incident; documentary rules alone do not
Pattern 5: Specify the Relationship between New and Existing Features as One of Four Values
Abstract layer:
When designing a new feature, always specify "which existing feature it relates to". The relationship type must be selected as one of: add / replace / coexist / phase-out. Adding without specification produces duplicate implementation, data conflict, and UI overlap. The maxims "don't fix on the side" and "ignore conflict with existing features" are mutually exclusive; when the new feature is a clear superset of the existing one, replacement = an exception to "don't fix on the side" and must be declared explicitly.
Concrete case:
A management tool's design added a new status-display badge. A legacy badge already existed, but the design specification did not state "delete the legacy badge" or "keep the legacy badge." The implementer interpreted the ambiguity as "keep both" and resulted in two badges drawn side-by-side on every target row. Later investigation articulated that "at design time, the legacy badge should have been replaced as the new badge is a superset" was the intent. The fix exhaustively removed the legacy badge JSX, related constants, i18n keys, and even the local interface in dialogs to align state. The structural cause was that the design-spec template lacked a "relationship to existing features" section.
Lesson:
The design specification (FSA / instructions) must always include fields for "related existing features (location / component / data source)," "relationship type (add / replace / coexist / phase-out)," and "deletion targets / retention targets". If the designer leaves these blank, the implementer has an obligation to ask before starting work.
Cross-domain reach:
- In ECU reverse-engineering, when developing a "new analysis method," failing to specify "replace" or "coexist" with the existing method causes data integrity to break under double analysis
- In engine-control map updates, failing to specify "full-region replace," "partial-region overwrite," or "parallel operation" between the new and old maps causes the engine to behave unintendedly
- In organizational change, failing to specify whether the existing workflow is "discontinued" or "operated in parallel" alongside the new workflow causes confusion
- In RAG-system development for conversational AI, when adding a new knowledge source, failing to specify "which to prioritize on duplication," "show both," or "decide priority by context" produces contradictory answers
- In legal-compliance system updates, failing to specify "transition period," "concurrent retention," or "automatic conversion" between new and old record formats breaks evidential consistency
Pattern 6: Eliminate Order-Dependence in Conditional Branches via Data-Driven Tables
Abstract layer:
When chaining multiple judgment rules as if A then X else if B then Y else if C then Z, the rule order can change the result. When a higher rule (A) subsumes the conditions of lower rules (B, C), reordering changes the verdict. This is order-dependence as a side effect. If the conditions can be rewritten as mutually independent dictionary lookups, table-ization structurally removes order-dependence. When an else if chain reaches three levels or more, consider data-driven table-ization.
Concrete case:
In a project-classification system, four-stage judgment rules (complete configuration / partial configuration / legacy / unknown) were written as an else if chain. Targets that satisfy R1 also satisfy R2's conditions; if a refactor placed R2 before R1, R1-complete targets would be classified as R2. The structurally correct expression is "a dictionary defining (condition, result) pairs per rule ID," with the judgment as a pure function returning the highest-priority ID whose condition is satisfied — eliminating order-dependence. Table-ization remained a refactoring candidate, not yet applied.
Lesson:
When an else if chain reaches three or more levels, consider data-driven table-ization. If the conditions are not independent (overlap with each other), express them with a table that explicitly assigns priorities. Tabularized rules dramatically improve testability, since each rule can be verified in isolation.
Cross-domain reach:
- An ECU control map is typically a "condition → output value" dictionary. Writing
if RPM > 5000 and TPS > 80 then ... with delays is harder to tune, test, and reverse-engineer than Map<(RPM_band, TPS_band), output>
- For ECU-reverse-engineering parsing rules per ECU type, replacing
else if with Map<ECU_signature, parser> makes new-ECU support a parser-addition only
- In embedded-device firmware, writing state transitions as
else if chains breeds order-dependent bugs frequently. State-transition tables improve verifiability
- In ML feature engineering, replacing conditional branches with lookups eases parallelization and optimization
- In rule-based judgment for legal contracts, table-ization with explicit priority order prevents disputes
- In RAG-system development for conversational AI, replacing user-intent classification's
else if with a Map<intent_label, response_template> is more extensible
Pattern 7: Negative Invariants Must Be Asserted by Tests
Abstract layer:
Negative invariants ("must NOT do X") cannot be sustained by documentary rules alone in the long run. They will be broken — at commit-review time, by a newcomer's added implementation, during refactoring, in large-scale changes — moments where someone fails to read the document (or reads it but loses focus) WILL happen. Negative invariants must be structurally guaranteed by tests, type systems, static analysis, or hardware mechanisms. "Documentary safety is not safety" is the core philosophy of ISO 26262 and applies to software in general.
Concrete case:
In a management tool, two negative invariants were established: "the auto path NEVER overwrites an existing marker" and "the list-removal feature NEVER touches the filesystem." The former is asserted by an explicit unit test (Case 1) and is also documented. The latter is documented but has no unit test. Therefore, the latter will be broken the moment someone in a future refactor adds an unlink call. Only when a test like Case 1 fails immediately on regression can a negative invariant be sustained. The unimplemented test is a technical debt and should have been prioritized by criticality.
Lesson:
When you find a "must NOT do X" in a codebase, check whether a test asserting it exists. If not, adding the test is the first priority. Documentary protection is a time bomb. In code reviews, when you see a comment like "this function presupposes X is not done," look for ways to add a test or enforce it via the type system.
Cross-domain reach:
- ISO 26262's functional safety requirements demand BOTH "safety goals (must NOT)" and "safety requirements (mechanisms that prevent)." Documentary safety is not safety, per the ISO philosophy
- In engine control, "fuel injection must not exceed engine tolerance" is enforced not only by software-layer limiters but also by hardware (injector spec) and CAN protocol-layer guarantees
- In smart contracts, negative invariants like "no reentrancy" or "do not call others" are structurally guaranteed by checks-effects-interactions or mutex patterns. Documentary rules alone produce The DAO–level incidents
- Database foreign-key and NOT NULL constraints are stronger when enforced at the DB layer than at the application logic layer
- Eiffel-style design-by-contract postconditions and invariants are checked at compile-time / runtime. Invariants in comments are only as durable as the comments themselves
- In RAG-system development, the negative invariant "do not generate false information" must be guaranteed in multiple layers: prompt constraints, source attribution, and verification flow
- In legal-compliance traceability, "do not tamper with evidence" must be enforced not only by operational rules but also physically — write-once media, hash verification, timestamped signatures
Pattern 8: Protect the Hierarchy between Explicit Intent and Automatic Inference
Abstract layer:
When a system stores both "values explicitly stated by humans (explicit intent)" and "values produced by machine inference (automatic inference)" in the same data field, the hierarchical relationship must be designed explicitly. Default to explicit intent > automatic inference, and require an "explicit overwrite-permission action" for automatic inference to override explicit intent. Without this hierarchy design, "data evaporation" occurs — the user's explicit input is silently overwritten on the next automatic update. Implement hierarchy protection with three components: (a) source-of-origin meta field, (b) staged-permission hierarchy, (c) UI visualization of the source.
Concrete case:
In a target-classification system, the metadata of each target could be written via two paths: "automatic inference" and "user manual input." By design, the auto path was guaranteed to "never overwrite existing data," and only the user-manual path performed an existing overwrite (with a UI confirmation dialog). A meta field stage_inferred distinguished "automatic inference (true) / explicit intent (false)," and the UI also distinguished them with a fade and an asterisk (*). The principle that explicit intent is hierarchically above automatic inference was applied consistently. If the hierarchy were violated, a user who manually entered protocol="manx" would see the value reverted to protocol="unknown" on the next automatic scan — a "data evaporation" event.
Lesson:
If a field can be written by both "user input" and "machine inference," implement hierarchy protection with all three: (a) a meta field distinguishing the source of origin, (b) a staged-permission hierarchy for overwrites, (c) UI visualization of the source. Missing any of the three causes "data evaporation" incidents.
Cross-domain reach:
- In LLM-based code completion, when both user edits and AI auto-corrections write to the same buffer, AI overwriting the user's most-recent edit destroys trust. Cursor- / Copilot-style editors struggle with this hierarchy design
- In autonomous vehicles, the "driver-action vs ADAS-intervention" hierarchy. The driver's explicit intervention (e.g., grabbing the wheel) must immediately override ADAS — a key principle of ISO 26262 SOTIF
- In engine-control tuning, if "values manually adjusted by the user" and "values learned automatically" land in the same table, source flags and priority are required
- In ECU-reverse-engineering tuning software, automatic Map import must not overwrite calibration values hand-written by the user
- In spreadsheets, the distinction between "user-input cells" and "formula cells." A UI where formulas overwrite manually entered values causes confusion
- In configuration management, the hierarchy of "user setting / organizational policy / default." That explicit intent (user setting) outranks automatic inference (default) is universal — from Windows Group Policy to AWS IAM Policy
- In RAG-system development, when the user corrects ("this answer is wrong"), the correction must take precedence over future RAG search results. Maintain the correction history as a higher-tier layer
3. Pattern for Extracting Patterns (Meta Thinking)
This section is the meta level of the skill.
When you encounter a new failure that existing Patterns cannot capture,
systematize the way to extract a new Pattern.
With this meta-thinking pattern, this skill can self-grow.
3-1. Five Steps for Pattern Extraction
When you experience a new failure, extract a Pattern through five steps:
Step 1: Write the surface of the failure in one sentence
It is fine to be very specific. "When clicking button X, instead of Y, Z appeared" is the right level. Capture file names, line numbers, observed symptoms candidly. Do not rush to abstract. Capture the fact while preserving specificity.
Step 2: Abstract the essence by one level
Discard file names, individual variable names, specific UI element names. Raise to "for a component X with a state, when trigger Y fires, expected value Z is not obtained." At this point, ask yourself "could this happen in other code?". If not, stop. The case has no Pattern-ization value.
Step 3: Extract a reusable principle from the essence
Make it domain-independent. Convert into a normative form: "in situation X, verify Y" or "when implementing X, write it with structure Y." Try giving it a name within 30 characters. If you cannot, the abstraction is still shallow. What cannot be named is not yet a Pattern.
Step 4: Test the principle in another domain
Consider whether the same trap could occur in another domain you know (your specialty / hobby / different project). If you cannot concretely identify a case in at least two domains, the Pattern has low generalization value. Ideally, three or more domains should yield concrete cases. Test in domains as far apart as possible — embedded development, data processing, UI/UX, organizational theory, natural science, law. The higher the test pass rate, the more robust the Pattern.
Step 5: Register as a Pattern, propose per the Self-Extension Rule
Describe in the Three-Layer Structure (abstract → concrete → lesson + cross-domain reach). Propose in §6 ("Reduction to the Pattern Catalog") of the completion report. After Design AI review and adoption decision, the Pattern is formally added to this skill.
3-2. The Three-Stage Self-Reflection (Inner Driver Alongside Pattern Extraction)
When you encounter a new failure, hold the following three-stage structure as inner posture:
Acknowledge
Say "I had not even imagined this" honestly. Do not make excuses. Acknowledging what you did not notice means acknowledging what you did not know, which makes the boundary of your knowledge visible.
Regret
Articulate "but there was room to notice." Was the data there? Could you have reached it by flipping the perspective? Ask yourself. Verbalizing regret is what generates the energy for next time.
Specify the next move
Do not stop at abstraction. Articulate concrete exploration patterns: "next time, look at X" or "next time, add Y as a step in the reflection." A new Pattern extracted via the five steps is the most concrete tool for specifying the next move.
This three-stage structure is the inner driver of Pattern extraction. Executing the five steps without the inner three-stage structure produces only template-shaped patterns. Run both wheels together.
3-3. Watch out for Heuristic Over-fit
When consulting the Pattern Catalog, you may encounter symptoms that do not perfectly match any Pattern. At that point, humans (and LLMs) tend to force-fit the symptom to the closest Pattern due to cognitive bias. We call this heuristic over-fit.
Steps to Avoid Over-fit
- Articulate the symptom first — write it down before consulting the catalog
- Look at the catalog and self-rate the match: 0–100%
- ≥80%: follow the Pattern's three-layer structure
- 50–80%: refer to the Pattern but design an independent investigation plan
- <50%: treat as a new Pattern and start extraction with the five steps in §3-1
- Record Patterns you ruled out (why you rejected them)
- Over-fit warning signs:
- You start to think the symptom fits an existing Pattern only by deliberately re-phrasing the symptom — danger sign
- Verification steps were executed but the actual results differ from expectations — likely the wrong Pattern; form an alternative hypothesis
- The symptom persists after the fix, or a similar symptom appears elsewhere — over-fit misdiagnosis is likely
4. Self-Extension Rule (Continuous-Growth Mechanism)
This skill is not a finished document — it is a growing thinking framework, open to all CC users as a shared asset.
4-1. Self-Reflection Discipline at Task Completion
When CC completes a debugging task, fill out all required sections of debug-report.md. In particular, §6 ("Reduction to the Pattern Catalog") and §7 ("New Pattern Proposal" if applicable) are physically prevented from empty completion by the hard interlock.
4-2. Adoption Criteria (Generalizability)
| Criterion | Recommend Adoption | Reject |
|---|
| Likelihood of recurrence | Could happen in different projects / situations | Specific to this project / data |
| Abstraction difficulty | Fits a 30-character name and the three-layer structure | Too many specific details, abstraction is shallow |
| Cross-domain reach | At least two domains yield concrete cases | Applies to only one domain |
| Clarity of normative form | Expressible as "if X, do Y" | Action guidance is vague |
When uncertain, bias toward recommending adoption (avoid rejection bias). Design AI makes the final call.
4-3. Proposal Flow (Four Steps)
Step 1: CC self-proposes in the completion report (debug-report.md)
- §6 Reduction to the Pattern Catalog: 3-way choice
- §7 New Pattern Proposal: details if applicable
- Hook blocks empty completion
Step 2: Design AI reviews
- Generalizability assessment
- Check overlap / proximity with existing Patterns
- Adoption decision (when uncertain, bias toward adoption)
Step 3: After adoption, an instruction document is issued for CC to add the new Pattern
- Add the new Pattern to SKILL.md §2
- Sync with Golden distribution (ja/en)
- Ship to OSS via the sync script
Step 4: Diffusion to OSS
- The new Pattern is shared with all CC users via the distribution channel
- This is the essence of "growing toolbox"
4-4. Pattern Numbering Convention
- Extending the existing catalog → consecutive number (Pattern 9, Pattern 10, ...)
- Tentative ID →
Pattern-NEW-XX (promote to formal numbering when confirmed)
- Sub-Pattern of an existing Pattern →
Pattern N-a, Pattern N-b (when not an independent new Pattern)
4-5. Inheritance of the Underlying Thinking Framework
The §3 ("Pattern for Extracting Patterns") and §3-2 ("Three-Stage Self-Reflection") are abstractions of the thinking framework gained through past development. Without naming proper nouns, the thinking pattern is inherited. CC extracting a new Pattern runs the three-stage structure inwardly while executing the five steps.
5. Glossary
| Term | Definition |
|---|
| CC | Claude Code (the implementing AI) |
| CCPIT | Claude Code Protocol Interlock Tower |
| FSA | Function Spec Anchor |
| FM | Failure Mode |
| FMA | Failure Mode Analysis |
| Pattern | A debugging / design thinking pattern organized as a domain-independent abstract principle |
| Pattern Catalog | The core of §2. A collection of Patterns in three-layer structure |
| Three-Layer Structure | Abstract description → concrete case → lesson + cross-domain reach |
| Pattern for Extracting Patterns | Meta-thinking pattern. Five steps for extracting a new Pattern from a failure |
| Hard Interlock | Mechanism in the hooks layer that physically prevents leaving template fields blank |
| debug-report-gate | Stop hook implementing the hard interlock |
| The Minor-Marque Mechanic Mindset | The professional posture of building one's own tool when needed, instead of relying solely on existing tools |
| SST | Special Service Tool. A specialized tool used in mechanical work; in this skill, a metaphor for a self-built tool against an unknown bug |
| Heuristic Over-fit | The cognitive bias of force-fitting a symptom into the existing Pattern Catalog |
| Descriptive Reading | Reading data as past fact (What) |
| Prescriptive Reading | Reading data as design lesson, "how it should have been" (Should) |
| Explicit Intent | A value explicitly stated by a human (Pattern 8) |
| Automatic Inference | A value produced by machine inference (Pattern 8) |
| Negative Invariant | A protective obligation of "must not do X" (Pattern 7) |
| Data-Driven Table | A design that replaces conditional branching with dictionary lookup (Pattern 6) |
| Data Evaporation | An incident where explicit intent is silently overwritten by automatic inference (Pattern 8) |
| Three-Stage Self-Reflection | The three-step posture: Acknowledge → Regret → Specify the next move |
| Living Document | A document continuously updated as features evolve. This skill is one |
6. Reference Appendix: 27 Failure Modes Catalog (with Pattern Labels)
This appendix catalogs 27 specific failure modes accumulated in CCPIT development.
Each FM is labeled with the Pattern in §2 of which it serves as a concrete case.
The intended flow: a future CC reads Pattern N first, then references FM-XX as a concrete case.
For OSS users, this is offered as "CCPIT-specific reference cases."
Use it to check whether your own project has analogous Pattern-traps.
6-1. FM List (Symptom-Indexed, with Pattern Labels)
| FM ID | Symptom (summary) | Primary Pattern | Secondary Pattern |
|---|
| FM-A-01 | Launch button does not start CC | Pattern 4 (fire-and-forget invariant) | — |
| FM-A-02 | Launch options not applied | — | Pattern 5 (backward compat vs phase-out) |
| FM-A-03 | Some items in ⋯ menu unclickable | — | — |
| FM-A-04 | AutoMode anomaly | Pattern 5 (no legacy-flag retention = phase-out) | — |
| FM-A-05 | Banner anomaly after successful launch | — | — |
| FM-B-01 | Discovery does not find PJs | Pattern 1 (all roots vs specific roots) | — |
| FM-B-02 | Discovery over-detection | — | Pattern 5 (promotion to user setting) |
| FM-B-03 | [CRITICAL] Real files deleted by Remove | Pattern 4 (multi-layer for catastrophic ops) | Pattern 7 (vitest defense missing) |
| FM-B-04 | Select All / Deselect All broken | — | — |
| FM-C-01 | Two badges side-by-side (legacy + new) | Pattern 5 (relationship to existing features) | — |
| FM-C-02 | [CRITICAL] Existing marker overwritten | Pattern 4 | Pattern 7 + Pattern 8 (explicit vs auto) |
| FM-C-03 | All PJs show ? only | Pattern 6 (R1–R4 order-dependence) | Pattern 1 (all PJs vs specific PJs) |
| FM-C-04 | stage_inferred UI not reflected | Pattern 8 (explicit vs auto) | — |
| FM-C-05 | No re-render after Edit Marker save | — | — |
| FM-C-06 | Re-scan confirm skipped | Pattern 4 (confirm as one safety layer) | — |
| FM-C-07 | [CRITICAL] Global write occurred | Pattern 4 + Pattern 7 (path validation missing) | — |
| FM-C-08 | profiles load failure | — | — |
| FM-C-09 | "informational only" note missing in evidence | Pattern 3 (common-source-out-of-judgment) | — |
| FM-C-10 | Self-host PJ shows unknown/low (spec) | Pattern 3 (common-source-exclusion logic) | Pattern 2 (prescriptive reading of Self-host structure) |
| FM-C-11 | Non-standard value in badge (data issue) | Pattern 8 (user-input freedom) | — |
| FM-D-01 | Favorite not persisted | — | — |
| FM-D-02 | Reserved fields throw undefined | Pattern 5 (incremental rollout) | — |
| FM-D-03 | location_type abnormal | Pattern 5 (staged remote-feature rollout) | — |
| FM-FF-01 | UI persists after flag is OFF | Pattern 5 (hidden vs disable) | — |
| FM-FF-02 | Flag reflection delayed | — | — |
| FM-FF-03 | New flag breaks existing config | Pattern 5 (4-file sync) | Pattern 7 (mergeFeatures test) |
| FM-FF-04 | Flag interaction broken | Pattern 6 (combinatorial test missing) | Pattern 8 |
6-2. FM Details
For full details, refer to _Prompt/_Knowledge/debug-guide-archive_260430/ in the CCPIT development repository (7 files). This appendix is an index used to reference concrete cases from the Pattern Catalog.
Each FM follows the FMA format:
- Symptom (observable phenomenon)
- Scope of impact
- Known incidents
- Cause candidates
- Verification steps
- Files to modify
- Related vitest cases
- Caveats on repair (including prescriptive reading)
- Past repair history
Note for OSS users: the FMs above are failure modes specific to CCPIT's system (an Electron + React + TypeScript management tool). Direct application to your own project may not be possible, but the Pattern labels make the thinking framework transferable. Reading Pattern N first and then referencing the corresponding FM as a concrete case can spark the realization "an analogous Pattern-trap could exist in my project too."
6-3. "Grow" Rather than "Use"
This appendix is not a frozen archive. As CCPIT adds new features, new FMs will be added here. Each FM is linked to §2 Pattern Catalog through Pattern labels and serves as material for proposing new Patterns.
Handover to future CCs maintaining CCPIT development:
- Observe a new feature defect → append a new FM-XX to the end of this appendix
- If any existing Pattern in §2 applies, add a Pattern label
- If none applies, invoke §3 ("Pattern for Extracting Patterns") and propose a new Pattern
- After Design AI review and addition to §2, update the Pattern label of the FM
→ Fire next skills
- For investigation procedure (counter-evidence checks, exhaustive code-path enumeration), refer to skill:investigation
- For investigation report formatting, refer to skill:research-report
- Before entering the implementation phase, fire skill:rumination (Q1–Q4) and skill:refactoring (reflection rounds 1–2)
- Before declaring completion, refer to skill:completion-interlock and confirm that the debug-report-gate hook does not block
This skill is an OSS asset shared with all CC users.
Your contributions (proposals per §4 Self-Extension Rule) grow this thinking framework.
If you don't have the right tool, build one. That is the spirit of the Minor-Marque Mechanic.
