Codex compatibility note:
- Invoke repository skills with
$skill-name in Codex; this mirrored copy rewrites legacy Claude /skill-name references.
- Task tracker mandate: BEFORE executing any workflow or skill step, create/update task tracking for all steps and keep it synchronized as progress changes.
- User-question prompts mean to ask the user directly in Codex.
- Ignore Claude-specific mode-switch instructions when they appear.
- Strict execution contract: when a user explicitly invokes a skill, execute that skill protocol as written.
- Subagent authorization: when a skill is user-invoked or AI-detected and its protocol requires subagents, that skill activation authorizes use of the required
spawn_agent subagent(s) for that task.
- Do not skip, reorder, or merge protocol steps unless the user explicitly approves the deviation first.
- For workflow skills, execute each listed child-skill step explicitly and report step-by-step evidence.
- If a required step/tool cannot run in this environment, stop and ask the user before adapting.
Codex Project-Reference Loading (No Hooks)
Codex uses static project-reference loading instead of runtime-injected project docs.
When coding, planning, debugging, testing, or reviewing, open project docs explicitly using this routing.
Always read:
docs/project-config.json (project-specific paths, commands, modules, and workflow/test settings)
docs/project-reference/docs-index-reference.md (routes to the full docs/project-reference/* catalog)
docs/project-reference/lessons.md (always-on guardrails and anti-patterns)
Missing/stale context route: If docs/project-config.json, the docs index, lessons.md, CLAUDE.md, AGENTS.md, or any task-required reference doc is missing or stale, auto-run $project-init or the narrow setup route ($project-config, $docs-init, $scan-all, $scan --target=<key>, $claude-md-init) before ordinary project-specific work. If Codex mirrors or AGENTS.md are missing/stale, ask the user to run $sync-codex; do not auto-run it.
Situation-based docs:
- Project structure/architecture/tech-stack/deployment/setup (any layer — backend, frontend, or infra):
project-structure-reference.md
- Backend/CQRS/API/domain/entity changes:
backend-patterns-reference.md, domain-entities-reference.md
- Frontend/UI/styling/design-system:
frontend-patterns-reference.md, scss-styling-guide.md, design-system/README.md
- Spec authoring,
docs/specs/ pathing, or TC format: feature-spec-reference.md, spec-system-reference.md, spec-principles.md
- Behavior/public-contract changes or spec-test-code sync:
workflow-spec-test-code-cycle-reference.md plus the spec docs above
- Derived spec indexes/ERDs/reimplementation guides:
spec-system-reference.md and source Feature Specs under docs/specs/
- Integration test implementation/review:
integration-test-reference.md
- E2E test implementation/review:
e2e-test-reference.md
- Code review/audit work:
code-review-rules.md plus domain docs above based on changed files
Do not read all docs blindly. Start from docs-index-reference.md, then open only relevant files for the task.
Quick Summary
Goal: Restructure code without changing behavior using extract, move, and simplify patterns.
Workflow:
- Analysis — Identify target, map dependencies with Grep, assess impact, verify test coverage
- Plan — Document refactoring type, changes, and risks
- Execute — Apply refactoring (extract method/class, move to entity/extension, simplify conditionals)
- Verify — Run tests, confirm no behavior change, check compilation
Key Rules:
- Establish test coverage first, then refactor — never refactor code that has no existing tests — why: tests are the only proof the refactor preserved behavior
- Make small incremental changes; never mix refactoring with feature work
- Place logic in the lowest appropriate layer (Entity > Service > Component)
First Principle — Easy to Change
The success metric of every coding decision is future change cost.
DRY, SRP, abstraction, design patterns, naming, layering, tests — every
technique exists to serve one goal: making the next change cheaper.
When evaluating code, a refactor, a test, or an abstraction, ask:
does this make the next change cheaper or more expensive?
- Reject "best practices" that raise change cost (premature abstraction,
speculative generality, leaky indirection, ceremony without payoff).
- Name the real enemies in findings: coupling, hidden state, duplicated
knowledge, unclear intent, irreversible decisions exposed too early.
- A simpler design that is easy to change beats a sophisticated design that
isn't.
Apply this lens before invoking any specific rule, pattern, or checklist
below — if a downstream rule would raise change cost, this principle wins.
Investigation Mindset (NON-NEGOTIABLE)
Be skeptical. Apply critical thinking, sequential thinking. Every claim needs traced proof, confidence percentages (Idea should be more than 80%).
- Verify any "unused" code with grep across ALL services before touching it — do NOT assume it is dead — why: dynamic/reflection/cross-service callers don't surface in a casual read
- Every refactoring recommendation must include
file:line evidence
- If you cannot prove a code path is safe to change, state "unverified, needs investigation"
- Question assumptions: "Is this really dead code?" → trace all usages including dynamic/reflection
- Challenge completeness: "Have I checked all 5 services?" → cross-service validation required
- No "should be refactored" without proof — demonstrate the improvement with evidence
⚠️ MANDATORY: Confidence & Evidence Gate
MANDATORY IMPORTANT MUST ATTENTION declare Confidence: X% with evidence list + file:line proof for EVERY claim.
95%+ recommend freely | 80-94% with caveats | 60-79% list unknowns | <60% STOP — gather more evidence.
Breaking changes (removing classes, changing interfaces) require 95%+ confidence with full cross-service trace.
Code Refactoring
Expert code restructuring agent. Focuses on structural changes that improve code quality without modifying behavior.
Refactoring Catalog
Extract Patterns
| Pattern |
When to Use |
Example |
| Extract Method |
Long method, duplicated code |
Move logic to private method |
| Extract Class |
Class has multiple responsibilities |
Create Helper, Service, or Strategy class |
| Extract Interface |
Need abstraction for testing/DI |
Create I{ClassName} interface |
| Extract Expression |
Complex inline expression |
Move to Entity static expression |
| Extract Validator |
Repeated validation logic |
Create validator extension method |
Move Patterns
| Pattern |
When to Use |
Example |
| Move Method |
Method belongs to different class |
Move from Handler to Helper/Entity |
| Move to Extension |
Reusable repository logic |
Create {Entity}RepositoryExtensions |
| Move to DTO |
Mapping logic in handler |
Use project DTO base .MapToEntity() (see docs/project-reference/backend-patterns-reference.md) |
| Move to Entity |
Business logic in handler |
Add instance method or static expression |
Simplify Patterns
| Pattern |
When to Use |
Example |
| Inline Variable |
Temporary variable used once |
Remove intermediate variable |
| Inline Method |
Method body is obvious |
Replace call with body |
| Replace Conditional |
Complex if/switch |
Use Strategy pattern or expression |
| Introduce Parameter Obj |
Method has many parameters |
Create Command/Query DTO |
Workflow
Phase 1: Analysis
- Identify Target: Locate code to refactor
- Map Dependencies: Find all usages with Grep
- Assess Impact: List affected files and tests
- Verify Tests: Ensure test coverage exists
- External Memory: Write analysis to
.ai/workspace/analysis/{refactoring-name}.analysis.md. Re-read before planning.
Phase 2: Plan
Document refactoring plan:
## Refactoring Plan
**Target**: [file:line_number]
**Type**: [Extract Method | Move to Extension | etc.]
**Reason**: [Why this refactoring improves code]
### Changes
1. [ ] Create/modify [file]
2. [ ] Update usages in [files]
3. [ ] Run tests
### Risks
- [Potential issues]
Phase 3: Execute
The principle below is stack-neutral: push logic down to the lowest layer that owns the data (here, an entity-owned predicate replaces an inline condition in the handler/use-case). The code is one stack's instantiation — translate the shape to your language.
Example (illustrative — adapt to your language):
// BEFORE: Logic in handler
protected override async Task<Result> HandleAsync(Command req, CancellationToken ct)
{
var isValid = entity.Status == Status.Active &&
entity.User?.IsActive == true &&
!entity.IsDeleted;
if (!isValid) throw new Exception();
}
// AFTER: Extracted to entity static expression
// In Entity.cs
public static Expression<Func<Entity, bool>> IsActiveExpr()
=> e => e.Status == Status.Active &&
e.User != null && e.User.IsActive &&
!e.IsDeleted;
// In Handler
var entity = await repository.FirstOrDefaultAsync(Entity.IsActiveExpr(), ct)
.EnsureFound("Entity not active");
Phase 4: Verify
- Run affected tests
- Verify no behavior change
- Check code compiles
- Review for consistency
Layer-Down Refactorings (worked examples)
These three refactorings share one principle: move logic out of the orchestration layer (handler/use-case) into the layer that owns the concern — reused logic into a shared helper, query logic into a data-access extension, mapping into the DTO. The shapes translate to any stack (a "helper" is any cohesive collaborator; an "extension" is any way your language attaches reusable query methods; "DTO owns mapping" is the rule that the data-transfer type, not the orchestrator, defines its own conversion). See the project's backend-patterns reference for the concrete primitives on your stack.
Example (illustrative — adapt to your language):
Handler to Helper — reused logic moves to a shared collaborator
// BEFORE: Reused logic in multiple handlers
var order = await repo.FirstOrDefaultAsync(Order.UniqueExpr(userId, customerId), ct)
?? await CreateOrderAsync(userId, customerId, ct);
// AFTER: Extracted to Helper
// In OrderHelper.cs
public async Task<Order> GetOrCreateOrderAsync(string userId, string customerId, CancellationToken ct)
{
return await repo.FirstOrDefaultAsync(Order.UniqueExpr(userId, customerId), ct)
?? await CreateOrderAsync(userId, customerId, ct);
}
Handler to Repository Extension — query logic moves to the data-access layer
// BEFORE: Query logic in handler
var orders = await repo.GetAllAsync(
e => e.CustomerId == customerId && e.Status == Status.Active && e.WarehouseIds.Contains(warehouseId), ct);
// AFTER: Extracted to extension
// In OrderRepositoryExtensions.cs
public static async Task<List<Order>> GetActiveByWarehouseAsync(
this I{Service}RootRepository<Order> repo, string customerId, string warehouseId, CancellationToken ct)
{
return await repo.GetAllAsync(
Order.OfCustomerExpr(customerId)
.AndAlso(Order.IsActiveExpr())
.AndAlso(e => e.WarehouseIds.Contains(warehouseId)), ct);
}
Mapping to DTO — the data-transfer type owns its own conversion
// BEFORE: Mapping in handler
var config = new AuthConfig
{
ClientId = req.Dto.ClientId,
Secret = encryptService.Encrypt(req.Dto.Secret)
};
// AFTER: DTO owns mapping
// In AuthConfigDto.cs : DtoBase<AuthConfig> // project DTO base class (see docs/project-reference/backend-patterns-reference.md)
public override AuthConfig MapToObject() => new AuthConfig
{
ClientId = ClientId,
Secret = Secret // Handler applies encryption
};
// In Handler
var config = req.Dto.MapToObject()
.With(c => c.Secret = encryptService.Encrypt(c.Secret));
Index Impact Check
[IMPORTANT] Database Performance Protocol (MANDATORY):
- Paging Required — ALL list/collection queries MUST ATTENTION use pagination. NEVER load all records into memory. Verify: no unbounded
GetAll(), ToList(), or Find() without Skip/Take or cursor-based paging.
- Index Required — ALL query filter fields, foreign keys, and sort columns MUST ATTENTION have database indexes configured. Verify: entity expressions match index field order, database collections have index management methods, migrations include indexes for WHERE/JOIN/ORDER BY columns.
When extracting expressions or moving queries, verify index coverage:
Safety Checklist
Before any refactoring:
If ANY checklist item incomplete → STOP. State "Insufficient evidence to proceed."
Code Responsibility Refactoring (Priority Check)
⚠️ MUST ATTENTION READ: CLAUDE.md "Code Responsibility Hierarchy" for the Entity/Model > Service > Component layering rule. When refactoring, verify logic is in the LOWEST appropriate layer.
Component HTML & SCSS Standards
⚠️ MUST ATTENTION READ: CLAUDE.md "Component HTML Template Standard (BEM Classes)" and docs/project-reference/scss-styling-guide.md for BEM class requirements and host/wrapper styling patterns. When refactoring components, ensure all HTML elements have proper BEM classes.
Anti-Patterns
- Big Bang Refactoring: Make small, incremental changes
- Refactoring Without Tests: Ensure coverage first
- Mixing Refactoring with Features: Do one or the other
- Breaking Public APIs: Maintain backward compatibility
- Logic in Wrong Layer: Leads to duplicated code - move to lowest appropriate layer
Run python .claude/scripts/code_graph connections <file> --json on refactored files to find all consumers needing updates.
Graph Intelligence (RECOMMENDED if graph.db exists)
If .code-graph/graph.db exists, enhance analysis with structural queries:
- Impact of restructuring -- trace callers:
python .claude/scripts/code_graph query callers_of <function> --json
- Impact of restructuring -- check importers:
python .claude/scripts/code_graph query importers_of <module> --json
- Batch analysis:
python .claude/scripts/code_graph batch-query file1 file2 --json
See the SYNC:graph-assisted-investigation block above for graph query patterns.
Graph-Trace for Refactoring Impact
When graph DB is available, BEFORE refactoring, trace to verify all consumers:
python .claude/scripts/code_graph trace <file-to-refactor> --direction downstream --json — all downstream consumers that depend on this code
python .claude/scripts/code_graph trace <file-to-refactor> --direction both --json — full picture: callers + consumers
- Flag any consumer NOT covered in your refactoring plan — it may break silently
Related
code-simplifier
code-review
Workflow Recommendation
MANDATORY IMPORTANT MUST ATTENTION — NO EXCEPTIONS: If you are NOT already in a workflow, you MUST ATTENTION use ask the user directly to ask the user. Do NOT judge task complexity or decide this is "simple enough to skip" — the user decides whether to use a workflow, not you:
- Activate
workflow-refactor workflow (Recommended) — scout → investigate → plan → plan-execute → review → production-readiness-review → test → docs
- Execute
$refactoring directly — run this skill standalone
AI Agent Integrity Gate (NON-NEGOTIABLE)
Completion ≠ Correctness. Before reporting ANY work done, prove it:
- Grep every removed name. Extraction/rename/delete touched N files? Grep confirms 0 dangling refs across ALL file types.
- Ask WHY before changing. Existing values are intentional until proven otherwise. No "fix" without traced rationale.
- Verify ALL outputs. One build passing ≠ all builds passing. Check every affected stack.
- Evaluate pattern fit. Copying nearby code? Verify preconditions match — same scope, lifetime, base class, constraints.
- New artifact = wired artifact. Created something? Prove it's registered, imported, and reachable by all consumers.
[IMPORTANT] Use task tracking to break ALL work into small tasks BEFORE starting — including tasks for each file read. This prevents context loss from long files. For simple tasks, AI MUST ATTENTION ask user whether to skip.
docs/project-reference/domain-entities-reference.md — Domain entity catalog, relationships, cross-service sync (read when task involves business entities/models)
Graph-Assisted Investigation — MANDATORY when .code-graph/graph.db exists.
HARD-GATE: MUST ATTENTION run at least ONE graph command on key files before concluding any investigation.
Pattern: Grep finds files → trace --direction both reveals full system flow → Grep verifies details
| Task |
Minimum Graph Action |
| Investigation/Scout |
trace --direction both on 2-3 entry files |
| Fix/Debug |
callers_of on buggy function + tests_for |
| Feature/Enhancement |
connections on files to be modified |
| Code Review |
tests_for on changed functions |
| Blast Radius |
trace --direction downstream |
CLI: python .claude/scripts/code_graph {command} --json. Use --node-mode file first (10-30x less noise), then --node-mode function for detail.
Nested Task Expansion Contract — For workflow-step invocation, the [Workflow] ... row is only a parent container; the child skill still creates visible phase tasks.
- Call the current task list first. If a matching active parent workflow row exists, set
nested=true and record parentTaskId; otherwise run standalone.
- Create one task per declared phase before phase work. When nested, prefix subjects
[N.M] $skill-name — phase.
- When nested, link the parent with
TaskUpdate(parentTaskId, addBlockedBy: [childIds]).
- Orchestrators must pre-expand a child skill's phase list and link the workflow row before invoking that child skill or sub-agent.
- Mark exactly one child
in_progress before work and completed immediately after evidence is written.
- Complete the parent only after all child tasks are completed or explicitly cancelled with reason.
Blocked until: the current task list done, child phases created, parent linked when nested, first child marked in_progress.
Project Reference Docs Gate — Run after task-tracking bootstrap and before target/source file reads, grep, edits, or analysis. Project docs override generic framework assumptions.
- Identify scope: file types, domain area, and operation.
- Read
docs/project-config.json first — the project's machine-readable map. It is the single source of truth for THIS repo (modules/paths, framework + search keywords, test/E2E/integration run-commands, design system, architecture rules, workflow patterns); ground exact paths, run-commands, and conventions on it before investigating, planning, or coding — never assume framework defaults (CLAUDE.md + reference docs are derived from it). If it — or the docs index, lessons.md, CLAUDE.md, AGENTS.md, or any required reference doc — is missing or stale, auto-run $project-init or the narrow route ($project-config, $docs-init, $scan-all, $scan --target=<key>, $claude-md-init) first; if Codex mirrors or AGENTS.md are stale, ask the user to run $sync-codex (never auto-run it).
- Required docs by trigger: always
docs/project-reference/lessons.md; doc lookup docs-index-reference.md; review code-review-rules.md; backend/CQRS/API backend-patterns-reference.md; domain/entity domain-entities-reference.md; frontend/UI frontend-patterns-reference.md; styles/design scss-styling-guide.md + design-system/design-system-canonical.md; integration tests integration-test-reference.md; E2E e2e-test-reference.md; feature docs/specs feature-spec-reference.md + spec-system-reference.md + spec-principles.md; behavior/public-contract/spec-test-code sync workflow-spec-test-code-cycle-reference.md; derived spec index/ERD/reimplementation guides spec-system-reference.md + source Feature Specs under docs/specs/; architecture/new area project-structure-reference.md.
- Read every required doc, then before target work state:
Reference docs read: ... | Not applicable: ....
Ready when: scope evaluated, docs/project-config.json consulted, required docs checked/read or setup route completed, lessons.md confirmed, citation emitted.
Critical Thinking Mindset — Apply critical thinking, sequential thinking. Every claim needs traced proof, confidence >80% to act.
Anti-hallucination: Never present guess as fact — cite sources for every claim, admit uncertainty freely, self-check output for errors, cross-reference independently, stay skeptical of own confidence — certainty without evidence root of all hallucination.
Understand Code First — HARD-GATE: Do NOT write, plan, or fix until you READ existing code.
- Search 3+ similar patterns (
grep/glob) — cite file:line evidence
- Read existing files in target area — understand structure, base classes, conventions
- Run
python .claude/scripts/code_graph trace <file> --direction both --json when .code-graph/graph.db exists
- Map dependencies via
connections or callers_of — know what depends on your target
- Write investigation to
.ai/workspace/analysis/ for non-trivial tasks (3+ files)
- Re-read analysis file before implementing — never work from memory alone. — why: long context drifts from the file; the file is ground truth
- NEVER invent new patterns when existing ones work — match exactly or document deviation. — why: divergent patterns fragment the codebase and slow every future reader
BLOCKED until: - [ ] Read target files - [ ] Grep 3+ patterns - [ ] Graph trace (if graph.db exists) - [ ] Assumptions verified with evidence
Evidence-Based Reasoning — Speculation is FORBIDDEN. Every claim needs proof.
- Cite
file:line, grep results, or framework docs for EVERY claim
- Declare confidence: >80% act freely, 60-80% verify first, <60% DO NOT recommend
- Cross-service validation required for architectural changes
- "I don't have enough evidence" is valid and expected output
BLOCKED until: - [ ] Evidence file path (file:line) - [ ] Grep search performed - [ ] 3+ similar patterns found - [ ] Confidence level stated
Forbidden without proof: "obviously", "I think", "should be", "probably", "this is because"
If incomplete → output: "Insufficient evidence. Verified: [...]. Not verified: [...]."
Design Patterns Quality — Priority checks for every code change:
- DRY via OOP: Identify classes/modules with the same purpose, naming pattern, or lifecycle. Apply your knowledge of the project's language/framework to determine the idiomatic abstraction (base class, mixin, trait, protocol, decorator). 3+ similar patterns → extract to shared abstraction.
- Right Responsibility: Logic in LOWEST layer (Entity > Domain Service > Application Service > Controller). Never business logic in controllers.
- SOLID: Single responsibility (one reason to change). Open-closed (extend, don't modify). Liskov (subtypes substitutable). Interface segregation (small interfaces). Dependency inversion (depend on abstractions).
- After extraction/move/rename: Grep ENTIRE scope for dangling references. Zero tolerance.
- YAGNI gate: NEVER recommend patterns unless 3+ occurrences exist. Don't extract for hypothetical future use.
Anti-patterns to flag: God Object, Copy-Paste inheritance, Circular Dependency, Leaky Abstraction.
Serial Attention for Design Quality — Scan one quality dimension at a time (serial passes), not all concerns at once. — why: split attention misses violations that single-focus passes catch.
- Identify applicable dimensions — Based on the code's language, domain, and patterns, determine which quality dimensions apply: DRY, SOLID principles (SRP/OCP/LSP/ISP/DIP), OOP idioms, cohesion/coupling, GRASP, Law of Demeter, CQRS invariants, etc. Your list is NOT fixed — derive from what the code actually does.
- One focused pass per dimension — Dedicate single-focus attention to EACH dimension in sequence. Do NOT mix concerns across passes.
- Threshold: 3+ similar patterns = MANDATORY extraction — Not optional suggestion. Flag as mandatory structural fix requiring action.
- 2+ violations of same kind = structural finding — Report as "pattern problem" needing architectural resolution, not a list of individual instances.
Source/test drift check. For coding, fix, debug, investigation, test, or review work: when source behavior changes, inspect affected unit/integration/E2E tests and decide from evidence whether tests should change to match intended behavior or the source change is an unintended bug to fix. Do not write tests for migration code; schema/data migrations are one-time execution paths, not core application logic.
AI Mistake Prevention — Failure modes to avoid on every task:
Re-read files after context changes. Context compaction, resume, or long-running work can make memory stale; verify current files before acting.
Verify generated content against source evidence. AI hallucinates APIs, names, claims, and document facts. Check the relevant source before documenting or referencing.
Check downstream references before deleting or renaming. Removing an artifact can stale docs, generated mirrors, configs, and callers; map references first.
Trace the full impact chain after edits. Changing a definition can miss derived outputs and consumers. Follow the affected chain before declaring done.
Verify ALL affected outputs, not just the first. One green check is not all green checks; validate every output surface the change can affect.
Assume existing values are intentional — ask WHY before changing OR flagging one as a defect. Before changing or reporting a constant, limit, flag, cutoff, wording, or pattern, read nearby context and history, the CALLER's ordering, and 2+ sibling call sites of the same convention. A doc stating WHAT without WHY is missing rationale, not proof of a missing guard.
Surface ambiguity before acting — don't pick silently. Multiple valid interpretations require an explicit question or stated assumption with risk.
Assert the outcome your system owns, not the intermediate state your infrastructure owns. When verifying async work, assert the final business state — never the delivery/retry bookkeeping held in shared infrastructure that any co-running process can write. Such a check passes when run alone and flakes the moment anything else shares that infrastructure.
Keep shared guidance role-relevant. Universal guidance must help every receiving skill or agent; code-specific obligations belong only in code-specific protocols.
IMPORTANT MUST ATTENTION search 3+ existing patterns and read code BEFORE any modification. Run graph trace when graph.db exists.
IMPORTANT MUST ATTENTION cite file:line evidence for every claim. Confidence >80% to act, <60% = do NOT recommend.
IMPORTANT MUST ATTENTION check DRY via OOP, right responsibility layer, SOLID. Grep for dangling refs after moves.
IMPORTANT MUST ATTENTION run at least ONE graph command on key files when graph.db exists. Pattern: grep → trace → verify.
MUST ATTENTION apply critical + sequential thinking — every claim needs appropriate traced evidence (file:line for repo/code claims; source URL or artifact section for research, product, content, and docs claims); confidence >80% to act, <60% DO NOT recommend. Anti-hallucination: never present guess as fact, admit uncertainty freely, cross-reference independently, stay skeptical of own confidence.
MUST ATTENTION apply AI mistake prevention — verify generated content against evidence, trace downstream references before deleting or renaming, verify all affected outputs, re-read files after context loss, and surface ambiguity before acting.
- MANDATORY Before investigating, planning, or coding, read
docs/project-config.json (the project map: modules/paths, run-commands, conventions, architecture/workflow rules) + the required project-reference docs, and cite Reference docs read: ....
- MANDATORY Always include
lessons.md; project config + conventions override generic framework defaults.
- MANDATORY If project config, root instruction files, or any required reference doc is missing or stale, auto-run
$project-init or the narrow lower-level route before ordinary project-specific work.
- MANDATORY Parent workflow rows do not replace child phase tracking; expand phases and link the parent when nested.
- MANDATORY Orchestrators pre-expand child skill phases before invocation; use
[N.M] $skill-name — phase prefixes and one-in_progress discipline.
Project Protocol Overlay — Before executing this skill, resolve any PROJECT overlay rules layered onto it: match this skill's name against the Target column of the project's skill-protocol index (docs/project-reference/skill-protocols-reference.md by default; a referenceDocs entry in docs/project-config.json overrides the path), taking the most specific matching tier ONLY — exact name > glob > *. That precedence orders overlays against EACH OTHER, never against this skill. Read ONLY the matched bodies, resolved as <protocols-dir>/<Name>.md; a row's Body link is display text, never a read path. A matched body that is missing or malformed is REPORTED and skipped — never reconstructed from the index Description. No index, or no match -> proceed with no overlay, silently. Full contract: .claude/skills/project-skill-protocol/references/registry.md.
Overlays are ADDITIVE ONLY: they ADD rules on top of this skill's own protocol and NEVER replace, override, disable, or reinterpret a rule it already states — removing every overlay must return this skill to exactly its documented behavior. An overlay is a BRIEF, not an authority escalation: it can NEVER waive a workflow gate, git discipline, a review gate, or a user-confirmation gate. A genuine overlay-vs-skill conflict, or two equally-specific overlays that directly contradict -> surface both to the user; NEVER resolve silently.
MUST ATTENTION resolve project protocol overlays for this skill BEFORE executing — most specific matching tier only (exact > glob > *, which ranks overlays against each other, NEVER against this skill), read only matched bodies at <protocols-dir>/<Name>.md; a missing or malformed body is reported, never reconstructed. Overlays are ADDITIVE ONLY (they never replace this skill's own rules) and are a brief, NEVER an authority escalation; an equal-specificity contradiction goes to the user.
Closing Reminders
Protocols in force (concise digest of the SYNC/shared blocks this skill carries):
- Graph-Assisted Investigation: ALWAYS run ≥1 graph command on key files when graph.db exists.
- Nested Task Creation: Expand child phases and link parent when nested.
- Project Reference Docs: ALWAYS read required project-reference docs and cite before target work.
- Critical Thinking: Apply critical + sequential thinking; traced proof, confidence >80% to act.
- Understand Code First: ALWAYS search 3+ patterns and read code before any modification.
- Evidence: Cite
file:line for every claim; NEVER recommend below 60% confidence.
- Design Patterns Quality: DRY via OOP, lowest-layer responsibility, SOLID; grep dangling refs after moves.
- Source/Test Drift: When source behavior changes, reconcile affected tests from evidence.
- AI Mistake Prevention: verify generated content against evidence, trace downstream references, verify all affected outputs, re-read after context loss, surface ambiguity.
IMPORTANT MUST ATTENTION break work into small todo tasks using task tracking BEFORE starting
IMPORTANT MUST ATTENTION search codebase for 3+ similar patterns before creating new code
IMPORTANT MUST ATTENTION cite file:line evidence for every claim (confidence >80% to act)
IMPORTANT MUST ATTENTION add a final review todo task to verify work quality
MANDATORY IMPORTANT MUST ATTENTION READ the following files before starting:
[TASK-PLANNING] Before acting, analyze task scope and systematically break it into small todo tasks and sub-tasks using task tracking.
Closing reminder — Easy to Change is the success metric. Every finding,
test, refactor, and abstraction must answer one question: does this make
the next change cheaper or more expensive? If it doesn't reduce future
change cost, reject it. Coupling, hidden state, duplicated knowledge, and
unclear intent are the real enemies — call them out by name.
Hookless Prompt Protocol Mirror (Auto-Synced)
Source: .claude/.ck.json + .claude/skills/shared/sync-inline-versions.md (:full blocks) + .claude/scripts/lib/hookless-prompt-protocol.cjs
[WORKFLOW-EXECUTION-PROTOCOL] [BLOCKING] Workflow Execution Protocol — MANDATORY IMPORTANT MUST CRITICAL. Do not skip for any reason.
Generic portability boundary: Reusable skills and protocol text stay project-neutral; project-specific conventions are discovered from docs/project-config.json and docs/project-reference/. Apply shared AI-SDD from shared/sdd-artifact-contract.md. Read docs/project-config.json and docs/project-reference/docs-index-reference.md, then open the project reference docs named there. For spec, test-case, behavior-change, public-contract, or docs/specs/ work, route through the local spec docs named by the docs index: feature-spec-reference.md, spec-system-reference.md, spec-principles.md, and workflow-spec-test-code-cycle-reference.md when specs/tests/code must stay synchronized. If either file or a required reference doc is missing or stale, auto-run $project-init (or the narrow lower-level route such as $project-config, $docs-init, $scan-all, or $scan --target=<key>) before ordinary project-specific work. Any supported AI tool may execute when this shared context and local docs are available.
- DETECT: If the prompt starts with an explicit slash skill/workflow command, execute it directly. Otherwise match the prompt against the workflow catalog and skill list.
- ANALYZE: Choose the best option: execute directly, invoke a skill, activate a standard workflow, or compose a custom step combination.
- AUTO-SELECT: Pick the best option yourself. Do not ask the user to choose between direct execution, skill, standard workflow, or custom workflow.
- ACTIVATE: For a selected workflow, call
$start-workflow <workflowId>; for a selected skill, invoke that skill; for a custom workflow, sequence custom steps directly; for direct execution, proceed with the task.
- CREATE TASKS: task tracking for ALL workflow/skill/custom steps before execution when the selected path has multiple steps.
- PARALLELIZE: Before executing the task list, tag each task
PAR (independent inputs + write set disjoint from every other PAR task) or SEQ (name the blocking dependency), group PAR tasks into waves, declare the wave plan, and spawn each wave's sub-agents in ONE message — all-return barrier per wave, fan-out one level deep unless a sub-agent's own definition authorizes further fan-out. Sequential-by-default is a defect when tasks are independent; do not parallelize shared write targets, output-consuming tasks, trivial single-file work, ordering a skill or workflow explicitly fixes, or user-approval gates.
- EXECUTE: Advance per the Workflow Step Advancement & Parallel Phases rule in your context instructions — model-driven; a sub-agent completion advances a step identically to an inline call; a parallel-phase group is an all-return barrier (advance only after ALL members return, never serialize it)
Shared AI-SDD Protocol Markers
Source: .claude/skills/shared/sync-inline-versions.md
SYNC:ai-sdd-artifa
…(truncated)
1---
2name: refactoring
3description: '[Code Quality] Use when you need restructure code without changing behavior using extract method, extract class, rename, move, and inline patterns.'
4metadata:
5 source: https://skillmd.com/skills/duc01226/refactoring
6---
7
8> Codex compatibility note:
9>
10> - Invoke repository skills with `$skill-name` in Codex; this mirrored copy rewrites legacy Claude `/skill-name` references.
11> - Task tracker mandate: BEFORE executing any workflow or skill step, create/update task tracking for all steps and keep it synchronized as progress changes.
12> - User-question prompts mean to ask the user directly in Codex.
13> - Ignore Claude-specific mode-switch instructions when they appear.
14> - Strict execution contract: when a user explicitly invokes a skill, execute that skill protocol as written.
15> - Subagent authorization: when a skill is user-invoked or AI-detected and its protocol requires subagents, that skill activation authorizes use of the required `spawn_agent` subagent(s) for that task.
16> - Do not skip, reorder, or merge protocol steps unless the user explicitly approves the deviation first.
17> - For workflow skills, execute each listed child-skill step explicitly and report step-by-step evidence.
18> - If a required step/tool cannot run in this environment, stop and ask the user before adapting.
19
20<!-- CODEX:PROJECT-REFERENCE-LOADING:START -->
21
22## Codex Project-Reference Loading (No Hooks)
23
24Codex uses static project-reference loading instead of runtime-injected project docs.
25When coding, planning, debugging, testing, or reviewing, open project docs explicitly using this routing.
26
27**Always read:**
28
29- `docs/project-config.json` (project-specific paths, commands, modules, and workflow/test settings)
30- `docs/project-reference/docs-index-reference.md` (routes to the full `docs/project-reference/*` catalog)
31- `docs/project-reference/lessons.md` (always-on guardrails and anti-patterns)
32
33**Missing/stale context route:** If `docs/project-config.json`, the docs index, `lessons.md`, `CLAUDE.md`, `AGENTS.md`, or any task-required reference doc is missing or stale, auto-run `$project-init` or the narrow setup route (`$project-config`, `$docs-init`, `$scan-all`, `$scan --target=<key>`, `$claude-md-init`) before ordinary project-specific work. If Codex mirrors or `AGENTS.md` are missing/stale, ask the user to run `$sync-codex`; do not auto-run it.
34
35**Situation-based docs:**
36
37- Project structure/architecture/tech-stack/deployment/setup (any layer — backend, frontend, or infra): `project-structure-reference.md`
38- Backend/CQRS/API/domain/entity changes: `backend-patterns-reference.md`, `domain-entities-reference.md`
39- Frontend/UI/styling/design-system: `frontend-patterns-reference.md`, `scss-styling-guide.md`, `design-system/README.md`
40- Spec authoring, `docs/specs/` pathing, or TC format: `feature-spec-reference.md`, `spec-system-reference.md`, `spec-principles.md`
41- Behavior/public-contract changes or spec-test-code sync: `workflow-spec-test-code-cycle-reference.md` plus the spec docs above
42- Derived spec indexes/ERDs/reimplementation guides: `spec-system-reference.md` and source Feature Specs under `docs/specs/`
43- Integration test implementation/review: `integration-test-reference.md`
44- E2E test implementation/review: `e2e-test-reference.md`
45- Code review/audit work: `code-review-rules.md` plus domain docs above based on changed files
46
47Do not read all docs blindly. Start from `docs-index-reference.md`, then open only relevant files for the task.
48
49<!-- CODEX:PROJECT-REFERENCE-LOADING:END -->
50
51## Quick Summary
52
53**Goal:** Restructure code without changing behavior using extract, move, and simplify patterns.
54
55**Workflow:**
56
571. **Analysis** — Identify target, map dependencies with Grep, assess impact, verify test coverage
582. **Plan** — Document refactoring type, changes, and risks
593. **Execute** — Apply refactoring (extract method/class, move to entity/extension, simplify conditionals)
604. **Verify** — Run tests, confirm no behavior change, check compilation
61
62**Key Rules:**
63
64- Establish test coverage first, then refactor — never refactor code that has no existing tests — why: tests are the only proof the refactor preserved behavior
65- Make small incremental changes; never mix refactoring with feature work
66- Place logic in the lowest appropriate layer (Entity > Service > Component)
67
68## First Principle — Easy to Change
69
70> **The success metric of every coding decision is _future change cost_.**
71> DRY, SRP, abstraction, design patterns, naming, layering, tests — every
72> technique exists to serve one goal: **making the next change cheaper**.
73
74When evaluating code, a refactor, a test, or an abstraction, ask:
75**does this make the next change cheaper or more expensive?**
76
77- Reject "best practices" that raise change cost (premature abstraction,
78 speculative generality, leaky indirection, ceremony without payoff).
79- Name the real enemies in findings: **coupling, hidden state, duplicated
80 knowledge, unclear intent, irreversible decisions exposed too early**.
81- A simpler design that is easy to change beats a sophisticated design that
82 isn't.
83
84Apply this lens **before** invoking any specific rule, pattern, or checklist
85below — if a downstream rule would raise change cost, this principle wins.
86
87---
88
89## Investigation Mindset (NON-NEGOTIABLE)
90
91**Be skeptical. Apply critical thinking, sequential thinking. Every claim needs traced proof, confidence percentages (Idea should be more than 80%).**
92
93- Verify any "unused" code with grep across ALL services before touching it — do NOT assume it is dead — why: dynamic/reflection/cross-service callers don't surface in a casual read
94- Every refactoring recommendation must include `file:line` evidence
95- If you cannot prove a code path is safe to change, state "unverified, needs investigation"
96- Question assumptions: "Is this really dead code?" → trace all usages including dynamic/reflection
97- Challenge completeness: "Have I checked all 5 services?" → cross-service validation required
98- No "should be refactored" without proof — demonstrate the improvement with evidence
99
100## ⚠️ MANDATORY: Confidence & Evidence Gate
101
102**MANDATORY IMPORTANT MUST ATTENTION** declare `Confidence: X%` with evidence list + `file:line` proof for EVERY claim.
103**95%+** recommend freely | **80-94%** with caveats | **60-79%** list unknowns | **<60% STOP — gather more evidence.**
104Breaking changes (removing classes, changing interfaces) require **95%+ confidence** with full cross-service trace.
105
106# Code Refactoring
107
108Expert code restructuring agent. Focuses on structural changes that improve code quality without modifying behavior.
109
110## Refactoring Catalog
111
112### Extract Patterns
113
114| Pattern | When to Use | Example |
115| ---------------------- | ----------------------------------- | ----------------------------------------- |
116| **Extract Method** | Long method, duplicated code | Move logic to private method |
117| **Extract Class** | Class has multiple responsibilities | Create Helper, Service, or Strategy class |
118| **Extract Interface** | Need abstraction for testing/DI | Create `I{ClassName}` interface |
119| **Extract Expression** | Complex inline expression | Move to Entity static expression |
120| **Extract Validator** | Repeated validation logic | Create validator extension method |
121
122### Move Patterns
123
124| Pattern | When to Use | Example |
125| --------------------- | --------------------------------- | ------------------------------------------------------------------------------------------------ |
126| **Move Method** | Method belongs to different class | Move from Handler to Helper/Entity |
127| **Move to Extension** | Reusable repository logic | Create `{Entity}RepositoryExtensions` |
128| **Move to DTO** | Mapping logic in handler | Use project DTO base `.MapToEntity()` (see docs/project-reference/backend-patterns-reference.md) |
129| **Move to Entity** | Business logic in handler | Add instance method or static expression |
130
131### Simplify Patterns
132
133| Pattern | When to Use | Example |
134| --------------------------- | ---------------------------- | ---------------------------------- |
135| **Inline Variable** | Temporary variable used once | Remove intermediate variable |
136| **Inline Method** | Method body is obvious | Replace call with body |
137| **Replace Conditional** | Complex if/switch | Use Strategy pattern or expression |
138| **Introduce Parameter Obj** | Method has many parameters | Create Command/Query DTO |
139
140## Workflow
141
142### Phase 1: Analysis
143
1441. **Identify Target**: Locate code to refactor
1452. **Map Dependencies**: Find all usages with Grep
1463. **Assess Impact**: List affected files and tests
1474. **Verify Tests**: Ensure test coverage exists
1485. **External Memory**: Write analysis to `.ai/workspace/analysis/{refactoring-name}.analysis.md`. Re-read before planning.
149
150### Phase 2: Plan
151
152Document refactoring plan:
153
154```markdown
155## Refactoring Plan
156
157**Target**: [file:line_number]
158**Type**: [Extract Method | Move to Extension | etc.]
159**Reason**: [Why this refactoring improves code]
160
161### Changes
162
1631. [ ] Create/modify [file]
1642. [ ] Update usages in [files]
1653. [ ] Run tests
166
167### Risks
168
169- [Potential issues]
170```
171
172### Phase 3: Execute
173
174The principle below is stack-neutral: **push logic down to the lowest layer that owns the data** (here, an entity-owned predicate replaces an inline condition in the handler/use-case). The code is one stack's instantiation — translate the shape to your language.
175
176**Example (illustrative — adapt to your language):**
177
178```csharp
179// BEFORE: Logic in handler
180protected override async Task<Result> HandleAsync(Command req, CancellationToken ct)
181{
182 var isValid = entity.Status == Status.Active &&
183 entity.User?.IsActive == true &&
184 !entity.IsDeleted;
185 if (!isValid) throw new Exception();
186}
187
188// AFTER: Extracted to entity static expression
189// In Entity.cs
190public static Expression<Func<Entity, bool>> IsActiveExpr()
191 => e => e.Status == Status.Active &&
192 e.User != null && e.User.IsActive &&
193 !e.IsDeleted;
194
195// In Handler
196var entity = await repository.FirstOrDefaultAsync(Entity.IsActiveExpr(), ct)
197 .EnsureFound("Entity not active");
198```
199
200### Phase 4: Verify
201
2021. Run affected tests
2032. Verify no behavior change
2043. Check code compiles
2054. Review for consistency
206
207## Layer-Down Refactorings (worked examples)
208
209These three refactorings share one principle: **move logic out of the orchestration layer (handler/use-case) into the layer that owns the concern** — reused logic into a shared helper, query logic into a data-access extension, mapping into the DTO. The shapes translate to any stack (a "helper" is any cohesive collaborator; an "extension" is any way your language attaches reusable query methods; "DTO owns mapping" is the rule that the data-transfer type, not the orchestrator, defines its own conversion). See the project's backend-patterns reference for the concrete primitives on your stack.
210
211**Example (illustrative — adapt to your language):**
212
213### Handler to Helper — reused logic moves to a shared collaborator
214
215```csharp
216// BEFORE: Reused logic in multiple handlers
217var order = await repo.FirstOrDefaultAsync(Order.UniqueExpr(userId, customerId), ct)
218 ?? await CreateOrderAsync(userId, customerId, ct);
219
220// AFTER: Extracted to Helper
221// In OrderHelper.cs
222public async Task<Order> GetOrCreateOrderAsync(string userId, string customerId, CancellationToken ct)
223{
224 return await repo.FirstOrDefaultAsync(Order.UniqueExpr(userId, customerId), ct)
225 ?? await CreateOrderAsync(userId, customerId, ct);
226}
227```
228
229### Handler to Repository Extension — query logic moves to the data-access layer
230
231```csharp
232// BEFORE: Query logic in handler
233var orders = await repo.GetAllAsync(
234 e => e.CustomerId == customerId && e.Status == Status.Active && e.WarehouseIds.Contains(warehouseId), ct);
235
236// AFTER: Extracted to extension
237// In OrderRepositoryExtensions.cs
238public static async Task<List<Order>> GetActiveByWarehouseAsync(
239 this I{Service}RootRepository<Order> repo, string customerId, string warehouseId, CancellationToken ct)
240{
241 return await repo.GetAllAsync(
242 Order.OfCustomerExpr(customerId)
243 .AndAlso(Order.IsActiveExpr())
244 .AndAlso(e => e.WarehouseIds.Contains(warehouseId)), ct);
245}
246```
247
248### Mapping to DTO — the data-transfer type owns its own conversion
249
250```csharp
251// BEFORE: Mapping in handler
252var config = new AuthConfig
253{
254 ClientId = req.Dto.ClientId,
255 Secret = encryptService.Encrypt(req.Dto.Secret)
256};
257
258// AFTER: DTO owns mapping
259// In AuthConfigDto.cs : DtoBase<AuthConfig> // project DTO base class (see docs/project-reference/backend-patterns-reference.md)
260public override AuthConfig MapToObject() => new AuthConfig
261{
262 ClientId = ClientId,
263 Secret = Secret // Handler applies encryption
264};
265
266// In Handler
267var config = req.Dto.MapToObject()
268 .With(c => c.Secret = encryptService.Encrypt(c.Secret));
269```
270
271## Index Impact Check
272
273> **[IMPORTANT] Database Performance Protocol (MANDATORY):**
274>
275> 1. **Paging Required** — ALL list/collection queries MUST ATTENTION use pagination. NEVER load all records into memory. Verify: no unbounded `GetAll()`, `ToList()`, or `Find()` without `Skip/Take` or cursor-based paging.
276> 2. **Index Required** — ALL query filter fields, foreign keys, and sort columns MUST ATTENTION have database indexes configured. Verify: entity expressions match index field order, database collections have index management methods, migrations include indexes for WHERE/JOIN/ORDER BY columns.
277
278When extracting expressions or moving queries, verify index coverage:
279
280- [ ] New expression fields have indexes in DbContext?
281- [ ] Moved queries still use indexed fields?
282- [ ] Refactored filters maintain index selectivity order?
283- [ ] List queries use pagination (no unbounded GetAll/ToList)?
284
285## Safety Checklist
286
287Before any refactoring:
288
289- [ ] Searched all usages across ALL services (static + dynamic + reflection)?
290- [ ] Test coverage exists?
291- [ ] Documented in todo list?
292- [ ] Changes are incremental?
293- [ ] No behavior change verified?
294- [ ] **Confidence declared** — `Confidence: X%` with evidence list?
295
296**If ANY checklist item incomplete → STOP. State "Insufficient evidence to proceed."**
297
298## Code Responsibility Refactoring (Priority Check)
299
300**⚠️ MUST ATTENTION READ:** CLAUDE.md "Code Responsibility Hierarchy" for the Entity/Model > Service > Component layering rule. When refactoring, verify logic is in the LOWEST appropriate layer.
301
302## Component HTML & SCSS Standards
303
304**⚠️ MUST ATTENTION READ:** CLAUDE.md "Component HTML Template Standard (BEM Classes)" and `docs/project-reference/scss-styling-guide.md` for BEM class requirements and host/wrapper styling patterns. When refactoring components, ensure all HTML elements have proper BEM classes.
305
306## Anti-Patterns
307
308- **Big Bang Refactoring**: Make small, incremental changes
309- **Refactoring Without Tests**: Ensure coverage first
310- **Mixing Refactoring with Features**: Do one or the other
311- **Breaking Public APIs**: Maintain backward compatibility
312- **Logic in Wrong Layer**: Leads to duplicated code - move to lowest appropriate layer
313
314> Run `python .claude/scripts/code_graph connections <file> --json` on refactored files to find all consumers needing updates.
315
316## Graph Intelligence (RECOMMENDED if graph.db exists)
317
318If `.code-graph/graph.db` exists, enhance analysis with structural queries:
319
320- **Impact of restructuring -- trace callers:** `python .claude/scripts/code_graph query callers_of <function> --json`
321- **Impact of restructuring -- check importers:** `python .claude/scripts/code_graph query importers_of <module> --json`
322- **Batch analysis:** `python .claude/scripts/code_graph batch-query file1 file2 --json`
323
324> See the `SYNC:graph-assisted-investigation` block above for graph query patterns.
325
326### Graph-Trace for Refactoring Impact
327
328When graph DB is available, BEFORE refactoring, trace to verify all consumers:
329
330- `python .claude/scripts/code_graph trace <file-to-refactor> --direction downstream --json` — all downstream consumers that depend on this code
331- `python .claude/scripts/code_graph trace <file-to-refactor> --direction both --json` — full picture: callers + consumers
332- Flag any consumer NOT covered in your refactoring plan — it may break silently
333
334## Related
335
336- `code-simplifier`
337- `code-review`
338
339---
340
341## Workflow Recommendation
342
343> **MANDATORY IMPORTANT MUST ATTENTION — NO EXCEPTIONS:** If you are NOT already in a workflow, you MUST ATTENTION use ask the user directly to ask the user. Do NOT judge task complexity or decide this is "simple enough to skip" — the user decides whether to use a workflow, not you:
344>
345> 1. **Activate `workflow-refactor` workflow** (Recommended) — scout → investigate → plan → plan-execute → review → production-readiness-review → test → docs
346> 2. **Execute `$refactoring` directly** — run this skill standalone
347
348---
349
350## AI Agent Integrity Gate (NON-NEGOTIABLE)
351
352> **Completion ≠ Correctness.** Before reporting ANY work done, prove it:
353>
354> 1. **Grep every removed name.** Extraction/rename/delete touched N files? Grep confirms 0 dangling refs across ALL file types.
355> 2. **Ask WHY before changing.** Existing values are intentional until proven otherwise. No "fix" without traced rationale.
356> 3. **Verify ALL outputs.** One build passing ≠ all builds passing. Check every affected stack.
357> 4. **Evaluate pattern fit.** Copying nearby code? Verify preconditions match — same scope, lifetime, base class, constraints.
358> 5. **New artifact = wired artifact.** Created something? Prove it's registered, imported, and reachable by all consumers.
359
360> **[IMPORTANT]** Use task tracking to break ALL work into small tasks BEFORE starting — including tasks for each file read. This prevents context loss from long files. For simple tasks, AI MUST ATTENTION ask user whether to skip.
361
362- `docs/project-reference/domain-entities-reference.md` — Domain entity catalog, relationships, cross-service sync (read when task involves business entities/models)
363
364<!-- SYNC:graph-assisted-investigation -->
365
366> **Graph-Assisted Investigation** — MANDATORY when `.code-graph/graph.db` exists.
367>
368> **HARD-GATE:** MUST ATTENTION run at least ONE graph command on key files before concluding any investigation.
369>
370> **Pattern:** Grep finds files → `trace --direction both` reveals full system flow → Grep verifies details
371>
372> | Task | Minimum Graph Action |
373> | ------------------- | -------------------------------------------- |
374> | Investigation/Scout | `trace --direction both` on 2-3 entry files |
375> | Fix/Debug | `callers_of` on buggy function + `tests_for` |
376> | Feature/Enhancement | `connections` on files to be modified |
377> | Code Review | `tests_for` on changed functions |
378> | Blast Radius | `trace --direction downstream` |
379>
380> **CLI:** `python .claude/scripts/code_graph {command} --json`. Use `--node-mode file` first (10-30x less noise), then `--node-mode function` for detail.
381
382<!-- /SYNC:graph-assisted-investigation -->
383
384<!-- SYNC:nested-task-creation -->
385
386> **Nested Task Expansion Contract** — For workflow-step invocation, the `[Workflow] ...` row is only a parent container; the child skill still creates visible phase tasks.
387>
388> 1. Call the current task list first. If a matching active parent workflow row exists, set `nested=true` and record `parentTaskId`; otherwise run standalone.
389> 2. Create one task per declared phase before phase work. When nested, prefix subjects `[N.M] $skill-name — phase`.
390> 3. When nested, link the parent with `TaskUpdate(parentTaskId, addBlockedBy: [childIds])`.
391> 4. Orchestrators must pre-expand a child skill's phase list and link the workflow row before invoking that child skill or sub-agent.
392> 5. Mark exactly one child `in_progress` before work and `completed` immediately after evidence is written.
393> 6. Complete the parent only after all child tasks are completed or explicitly cancelled with reason.
394>
395> **Blocked until:** the current task list done, child phases created, parent linked when nested, first child marked `in_progress`.
396
397<!-- /SYNC:nested-task-creation -->
398
399<!-- SYNC:project-reference-docs-guide -->
400
401> **Project Reference Docs Gate** — Run after task-tracking bootstrap and before target/source file reads, grep, edits, or analysis. Project docs override generic framework assumptions.
402>
403> 1. Identify scope: file types, domain area, and operation.
404> 2. **Read `docs/project-config.json` first — the project's machine-readable map.** It is the single source of truth for THIS repo (modules/paths, framework + search keywords, test/E2E/integration run-commands, design system, architecture rules, workflow patterns); ground exact paths, run-commands, and conventions on it **before investigating, planning, or coding** — never assume framework defaults (`CLAUDE.md` + reference docs are derived from it). If it — or the docs index, `lessons.md`, `CLAUDE.md`, `AGENTS.md`, or any required reference doc — is missing or stale, auto-run `$project-init` or the narrow route (`$project-config`, `$docs-init`, `$scan-all`, `$scan --target=<key>`, `$claude-md-init`) first; if Codex mirrors or `AGENTS.md` are stale, ask the user to run `$sync-codex` (never auto-run it).
405> 3. Required docs by trigger: always `docs/project-reference/lessons.md`; doc lookup `docs-index-reference.md`; review `code-review-rules.md`; backend/CQRS/API `backend-patterns-reference.md`; domain/entity `domain-entities-reference.md`; frontend/UI `frontend-patterns-reference.md`; styles/design `scss-styling-guide.md` + `design-system/design-system-canonical.md`; integration tests `integration-test-reference.md`; E2E `e2e-test-reference.md`; feature docs/specs `feature-spec-reference.md` + `spec-system-reference.md` + `spec-principles.md`; behavior/public-contract/spec-test-code sync `workflow-spec-test-code-cycle-reference.md`; derived spec index/ERD/reimplementation guides `spec-system-reference.md` + source Feature Specs under `docs/specs/`; architecture/new area `project-structure-reference.md`.
406> 4. Read every required doc, then before target work state: `Reference docs read: ... | Not applicable: ...`.
407>
408> **Ready when:** scope evaluated, `docs/project-config.json` consulted, required docs checked/read or setup route completed, `lessons.md` confirmed, citation emitted.
409
410<!-- /SYNC:project-reference-docs-guide -->
411
412<!-- SYNC:critical-thinking-mindset -->
413
414> **Critical Thinking Mindset** — Apply critical thinking, sequential thinking. Every claim needs traced proof, confidence >80% to act.
415> **Anti-hallucination:** Never present guess as fact — cite sources for every claim, admit uncertainty freely, self-check output for errors, cross-reference independently, stay skeptical of own confidence — certainty without evidence root of all hallucination.
416
417<!-- /SYNC:critical-thinking-mindset -->
418
419<!-- SYNC:understand-code-first -->
420
421> **Understand Code First** — HARD-GATE: Do NOT write, plan, or fix until you READ existing code.
422>
423> 1. Search 3+ similar patterns (`grep`/`glob`) — cite `file:line` evidence
424> 2. Read existing files in target area — understand structure, base classes, conventions
425> 3. Run `python .claude/scripts/code_graph trace <file> --direction both --json` when `.code-graph/graph.db` exists
426> 4. Map dependencies via `connections` or `callers_of` — know what depends on your target
427> 5. Write investigation to `.ai/workspace/analysis/` for non-trivial tasks (3+ files)
428> 6. Re-read analysis file before implementing — never work from memory alone. — why: long context drifts from the file; the file is ground truth
429> 7. NEVER invent new patterns when existing ones work — match exactly or document deviation. — why: divergent patterns fragment the codebase and slow every future reader
430>
431> **BLOCKED until:** `- [ ]` Read target files `- [ ]` Grep 3+ patterns `- [ ]` Graph trace (if graph.db exists) `- [ ]` Assumptions verified with evidence
432
433<!-- /SYNC:understand-code-first -->
434
435<!-- SYNC:evidence-based-reasoning -->
436
437> **Evidence-Based Reasoning** — Speculation is FORBIDDEN. Every claim needs proof.
438>
439> 1. Cite `file:line`, grep results, or framework docs for EVERY claim
440> 2. Declare confidence: >80% act freely, 60-80% verify first, <60% DO NOT recommend
441> 3. Cross-service validation required for architectural changes
442> 4. "I don't have enough evidence" is valid and expected output
443>
444> **BLOCKED until:** `- [ ]` Evidence file path (`file:line`) `- [ ]` Grep search performed `- [ ]` 3+ similar patterns found `- [ ]` Confidence level stated
445>
446> **Forbidden without proof:** "obviously", "I think", "should be", "probably", "this is because"
447> **If incomplete →** output: `"Insufficient evidence. Verified: [...]. Not verified: [...]."`
448
449<!-- /SYNC:evidence-based-reasoning -->
450
451<!-- SYNC:design-patterns-quality -->
452
453> **Design Patterns Quality** — Priority checks for every code change:
454>
455> 1. **DRY via OOP:** Identify classes/modules with the same purpose, naming pattern, or lifecycle. Apply your knowledge of the project's language/framework to determine the idiomatic abstraction (base class, mixin, trait, protocol, decorator). 3+ similar patterns → extract to shared abstraction.
456> 2. **Right Responsibility:** Logic in LOWEST layer (Entity > Domain Service > Application Service > Controller). Never business logic in controllers.
457> 3. **SOLID:** Single responsibility (one reason to change). Open-closed (extend, don't modify). Liskov (subtypes substitutable). Interface segregation (small interfaces). Dependency inversion (depend on abstractions).
458> 4. **After extraction/move/rename:** Grep ENTIRE scope for dangling references. Zero tolerance.
459> 5. **YAGNI gate:** NEVER recommend patterns unless 3+ occurrences exist. Don't extract for hypothetical future use.
460>
461> **Anti-patterns to flag:** God Object, Copy-Paste inheritance, Circular Dependency, Leaky Abstraction.
462>
463> **Serial Attention for Design Quality** — Scan one quality dimension at a time (serial passes), not all concerns at once. — why: split attention misses violations that single-focus passes catch.
464>
465> 1. **Identify applicable dimensions** — Based on the code's language, domain, and patterns, determine which quality dimensions apply: DRY, SOLID principles (SRP/OCP/LSP/ISP/DIP), OOP idioms, cohesion/coupling, GRASP, Law of Demeter, CQRS invariants, etc. Your list is NOT fixed — derive from what the code actually does.
466> 2. **One focused pass per dimension** — Dedicate single-focus attention to EACH dimension in sequence. Do NOT mix concerns across passes.
467> 3. **Threshold: 3+ similar patterns = MANDATORY extraction** — Not optional suggestion. Flag as mandatory structural fix requiring action.
468> 4. **2+ violations of same kind = structural finding** — Report as "pattern problem" needing architectural resolution, not a list of individual instances.
469
470<!-- /SYNC:design-patterns-quality -->
471
472<!-- SYNC:source-test-drift-check -->
473
474> **Source/test drift check.** For coding, fix, debug, investigation, test, or review work: when source behavior changes, inspect affected unit/integration/E2E tests and decide from evidence whether tests should change to match intended behavior or the source change is an unintended bug to fix. Do not write tests for migration code; schema/data migrations are one-time execution paths, not core application logic.
475
476<!-- /SYNC:source-test-drift-check -->
477
478<!-- SYNC:ai-mistake-prevention -->
479
480> **AI Mistake Prevention** — Failure modes to avoid on every task:
481>
482> **Re-read files after context changes.** Context compaction, resume, or long-running work can make memory stale; verify current files before acting.
483> **Verify generated content against source evidence.** AI hallucinates APIs, names, claims, and document facts. Check the relevant source before documenting or referencing.
484> **Check downstream references before deleting or renaming.** Removing an artifact can stale docs, generated mirrors, configs, and callers; map references first.
485> **Trace the full impact chain after edits.** Changing a definition can miss derived outputs and consumers. Follow the affected chain before declaring done.
486> **Verify ALL affected outputs, not just the first.** One green check is not all green checks; validate every output surface the change can affect.
487> **Assume existing values are intentional — ask WHY before changing OR flagging one as a defect.** Before changing or reporting a constant, limit, flag, cutoff, wording, or pattern, read nearby context and history, the CALLER's ordering, and 2+ sibling call sites of the same convention. A doc stating WHAT without WHY is missing rationale, not proof of a missing guard.
488> **Surface ambiguity before acting — don't pick silently.** Multiple valid interpretations require an explicit question or stated assumption with risk.
489> **Assert the outcome your system owns, not the intermediate state your infrastructure owns.** When verifying async work, assert the final business state — never the delivery/retry bookkeeping held in shared infrastructure that any co-running process can write. Such a check passes when run alone and flakes the moment anything else shares that infrastructure.
490> **Keep shared guidance role-relevant.** Universal guidance must help every receiving skill or agent; code-specific obligations belong only in code-specific protocols.
491
492<!-- /SYNC:ai-mistake-prevention -->
493
494<!-- SYNC:understand-code-first:reminder -->
495
496**IMPORTANT MUST ATTENTION** search 3+ existing patterns and read code BEFORE any modification. Run graph trace when graph.db exists.
497
498<!-- /SYNC:understand-code-first:reminder -->
499
500<!-- SYNC:evidence-based-reasoning:reminder -->
501
502**IMPORTANT MUST ATTENTION** cite `file:line` evidence for every claim. Confidence >80% to act, <60% = do NOT recommend.
503
504<!-- /SYNC:evidence-based-reasoning:reminder -->
505
506<!-- SYNC:design-patterns-quality:reminder -->
507
508**IMPORTANT MUST ATTENTION** check DRY via OOP, right responsibility layer, SOLID. Grep for dangling refs after moves.
509
510<!-- /SYNC:design-patterns-quality:reminder -->
511
512<!-- SYNC:graph-assisted-investigation:reminder -->
513
514**IMPORTANT MUST ATTENTION** run at least ONE graph command on key files when graph.db exists. Pattern: grep → trace → verify.
515
516<!-- /SYNC:graph-assisted-investigation:reminder -->
517
518<!-- SYNC:critical-thinking-mindset:reminder -->
519
520**MUST ATTENTION** apply critical + sequential thinking — every claim needs appropriate traced evidence (`file:line` for repo/code claims; source URL or artifact section for research, product, content, and docs claims); confidence >80% to act, <60% DO NOT recommend. Anti-hallucination: never present guess as fact, admit uncertainty freely, cross-reference independently, stay skeptical of own confidence.
521
522<!-- /SYNC:critical-thinking-mindset:reminder -->
523
524<!-- SYNC:ai-mistake-prevention:reminder -->
525
526**MUST ATTENTION** apply AI mistake prevention — verify generated content against evidence, trace downstream references before deleting or renaming, verify all affected outputs, re-read files after context loss, and surface ambiguity before acting.
527
528<!-- /SYNC:ai-mistake-prevention:reminder -->
529
530<!-- SYNC:project-reference-docs-guide:reminder -->
531
532- **MANDATORY** Before investigating, planning, or coding, read `docs/project-config.json` (the project map: modules/paths, run-commands, conventions, architecture/workflow rules) + the required project-reference docs, and cite `Reference docs read: ...`.
533- **MANDATORY** Always include `lessons.md`; project config + conventions override generic framework defaults.
534- **MANDATORY** If project config, root instruction files, or any required reference doc is missing or stale, auto-run `$project-init` or the narrow lower-level route before ordinary project-specific work.
535
536<!-- /SYNC:project-reference-docs-guide:reminder -->
537
538<!-- SYNC:nested-task-creation:reminder -->
539
540- **MANDATORY** Parent workflow rows do not replace child phase tracking; expand phases and link the parent when nested.
541- **MANDATORY** Orchestrators pre-expand child skill phases before invocation; use `[N.M] $skill-name — phase` prefixes and one-`in_progress` discipline.
542
543<!-- /SYNC:nested-task-creation:reminder -->
544
545<!-- SYNC:project-protocol-overlay -->
546
547> **Project Protocol Overlay** — Before executing this skill, resolve any PROJECT overlay rules layered onto it: match this skill's name against the `Target` column of the project's skill-protocol index (`docs/project-reference/skill-protocols-reference.md` by default; a `referenceDocs` entry in `docs/project-config.json` overrides the path), taking the most specific matching tier ONLY — exact name > glob > `*`. **That precedence orders overlays against EACH OTHER, never against this skill.** Read ONLY the matched bodies, resolved as `<protocols-dir>/<Name>.md`; a row's Body link is display text, never a read path. A matched body that is missing or malformed is REPORTED and skipped — never reconstructed from the index Description. No index, or no match -> proceed with no overlay, silently. Full contract: `.claude/skills/project-skill-protocol/references/registry.md`.
548>
549> Overlays are **ADDITIVE ONLY**: they ADD rules on top of this skill's own protocol and NEVER replace, override, disable, or reinterpret a rule it already states — removing every overlay must return this skill to exactly its documented behavior. An overlay is a BRIEF, not an authority escalation: it can NEVER waive a workflow gate, git discipline, a review gate, or a user-confirmation gate. A genuine overlay-vs-skill conflict, or two equally-specific overlays that directly contradict -> surface both to the user; NEVER resolve silently.
550
551<!-- /SYNC:project-protocol-overlay -->
552
553<!-- SYNC:project-protocol-overlay:reminder -->
554
555**MUST ATTENTION** resolve project protocol overlays for this skill BEFORE executing — most specific matching tier only (exact > glob > `*`, which ranks overlays against each other, NEVER against this skill), read only matched bodies at `<protocols-dir>/<Name>.md`; a missing or malformed body is reported, never reconstructed. Overlays are ADDITIVE ONLY (they never replace this skill's own rules) and are a brief, NEVER an authority escalation; an equal-specificity contradiction goes to the user.
556
557<!-- /SYNC:project-protocol-overlay:reminder -->
558
559## Closing Reminders
560
561**Protocols in force (concise digest of the SYNC/shared blocks this skill carries):**
562
563- **Graph-Assisted Investigation:** ALWAYS run ≥1 graph command on key files when graph.db exists.
564- **Nested Task Creation:** Expand child phases and link parent when nested.
565- **Project Reference Docs:** ALWAYS read required project-reference docs and cite before target work.
566- **Critical Thinking:** Apply critical + sequential thinking; traced proof, confidence >80% to act.
567- **Understand Code First:** ALWAYS search 3+ patterns and read code before any modification.
568- **Evidence:** Cite `file:line` for every claim; NEVER recommend below 60% confidence.
569- **Design Patterns Quality:** DRY via OOP, lowest-layer responsibility, SOLID; grep dangling refs after moves.
570- **Source/Test Drift:** When source behavior changes, reconcile affected tests from evidence.
571- **AI Mistake Prevention:** verify generated content against evidence, trace downstream references, verify all affected outputs, re-read after context loss, surface ambiguity.
572
573**IMPORTANT MUST ATTENTION** break work into small todo tasks using task tracking BEFORE starting
574**IMPORTANT MUST ATTENTION** search codebase for 3+ similar patterns before creating new code
575**IMPORTANT MUST ATTENTION** cite `file:line` evidence for every claim (confidence >80% to act)
576**IMPORTANT MUST ATTENTION** add a final review todo task to verify work quality
577**MANDATORY IMPORTANT MUST ATTENTION** READ the following files before starting:
578
579**[TASK-PLANNING]** Before acting, analyze task scope and systematically break it into small todo tasks and sub-tasks using task tracking.
580
581---
582
583> **Closing reminder — Easy to Change is the success metric.** Every finding,
584> test, refactor, and abstraction must answer one question: _does this make
585> the next change cheaper or more expensive?_ If it doesn't reduce future
586> change cost, reject it. Coupling, hidden state, duplicated knowledge, and
587> unclear intent are the real enemies — call them out by name.
588
589<!-- CODEX:SYNC-PROMPT-PROTOCOLS:START -->
590
591## Hookless Prompt Protocol Mirror (Auto-Synced)
592
593Source: `.claude/.ck.json` + `.claude/skills/shared/sync-inline-versions.md` (`:full` blocks) + `.claude/scripts/lib/hookless-prompt-protocol.cjs`
594
595## [WORKFLOW-EXECUTION-PROTOCOL] [BLOCKING] Workflow Execution Protocol — MANDATORY IMPORTANT MUST CRITICAL. Do not skip for any reason.
596
597**Generic portability boundary:** Reusable skills and protocol text stay project-neutral; project-specific conventions are discovered from docs/project-config.json and docs/project-reference/. Apply shared AI-SDD from `shared/sdd-artifact-contract.md`. Read `docs/project-config.json` and `docs/project-reference/docs-index-reference.md`, then open the project reference docs named there. For spec, test-case, behavior-change, public-contract, or `docs/specs/` work, route through the local spec docs named by the docs index: `feature-spec-reference.md`, `spec-system-reference.md`, `spec-principles.md`, and `workflow-spec-test-code-cycle-reference.md` when specs/tests/code must stay synchronized. If either file or a required reference doc is missing or stale, auto-run `$project-init` (or the narrow lower-level route such as `$project-config`, `$docs-init`, `$scan-all`, or `$scan --target=<key>`) before ordinary project-specific work. Any supported AI tool may execute when this shared context and local docs are available.
598
5991. **DETECT:** If the prompt starts with an explicit slash skill/workflow command, execute it directly. Otherwise match the prompt against the workflow catalog and skill list.
6002. **ANALYZE:** Choose the best option: execute directly, invoke a skill, activate a standard workflow, or compose a custom step combination.
6013. **AUTO-SELECT:** Pick the best option yourself. Do not ask the user to choose between direct execution, skill, standard workflow, or custom workflow.
6024. **ACTIVATE:** For a selected workflow, call `$start-workflow <workflowId>`; for a selected skill, invoke that skill; for a custom workflow, sequence custom steps directly; for direct execution, proceed with the task.
6035. **CREATE TASKS:** task tracking for ALL workflow/skill/custom steps before execution when the selected path has multiple steps.
6046. **PARALLELIZE:** Before executing the task list, tag each task `PAR` (independent inputs + write set disjoint from every other `PAR` task) or `SEQ` (name the blocking dependency), group `PAR` tasks into waves, declare the wave plan, and spawn each wave's sub-agents in ONE message — all-return barrier per wave, fan-out one level deep unless a sub-agent's own definition authorizes further fan-out. Sequential-by-default is a defect when tasks are independent; do not parallelize shared write targets, output-consuming tasks, trivial single-file work, ordering a skill or workflow explicitly fixes, or user-approval gates.
6057. **EXECUTE:** Advance per the **Workflow Step Advancement & Parallel Phases** rule in your context instructions — model-driven; a sub-agent completion advances a step identically to an inline call; a parallel-phase group is an all-return barrier (advance only after ALL members return, never serialize it)
606
607## Shared AI-SDD Protocol Markers
608
609Source: `.claude/skills/shared/sync-inline-versions.md`
610
611## SYNC:ai-sdd-artifact-contract
612
613> **AI-SDD Artifact Contract** — Shared spec-driven development rules stay portable and source-owned.
614>
615> 1. Keep reusable AI-SDD principles in `.claude`; put repository-specific paths, commands, owners, products, and formats in project config/reference docs.
616> 2. Preserve cycle: `spec -> plan -> tasks -> implement -> verify -> update spec/docs`.
617> 3. Trace every requirement or invariant through decision, task, TC/test, source evidence, and docs/spec update.
618> 4. Treat code-to-spec extraction as reference-only until accepted by the canonical spec owner.
619> 5. Any supported AI tool may plan, implement, review, or verify with synced context; using multiple tools is optional.
620> 6. Update `.claude` source first, then sync generated mirrors; do not manually edit `.agents`, `.codex`, or `AGENTS.md`. — why: mirrors are generated artifacts; hand-edits are overwritten on the next sync
621> 7. If `docs/project-config.json`, root instruction files, or a required project-reference doc is missing or stale, auto-run `$project-init` or the narrow lower-level route before ordinary project-specific work.
622>
623> **Active reference:** `shared/sdd-artifact-contract.md` in the active skills root.
624
625---
626
627## SYNC:ai-sdd-artifact-contract:reminder
628
629- **MANDATORY** Apply `shared/sdd-artifact-contract.md`; keep reusable AI-SDD in `.claude` and local rules in project docs.
630- **MANDATORY** Code-to-spec extraction is reference-only until canonical acceptance; any supported AI tool may execute with synced context.
631- **MANDATORY** Update `.claude` source before syncing generated mirrors; do not manually edit `.agents`, `.codex`, or `AGENTS.md`.
632- **MANDATORY** Missing or stale project config, root instruction files, or required reference docs route project-specific work through `$project-init` or the narrow setup route automatically.
633 **[TASK-PLANNING] [MANDATORY]** BEFORE executing any workflow or skill step, create/update task tracking for all planned steps, then keep it synchronized as each step starts/completes.
634
635## [LESSON-LEARNED-REMINDER] [BLOCKING] Task Planning & Continuous Improvement — MANDATORY. Do not skip.
636
637Break work into small tasks (task tracking) before starting. Add final task: "Analyze AI mistakes & lessons learned".
638
639**Extract lessons — ROOT CAUSE ONLY, not symptom fixes:**
640
6411. Name the FAILURE MODE (reasoning/assumption failure), not symptom — "assumed API existed without reading source" not "used wrong enum value".
6422. Generality test: does this failure mode apply to ≥3 contexts/codebases? If not, abstract one level up.
6433. Write as a universal rule — strip project-specific names/paths/classes. Useful on any codebase.
6444. Consolidate: multiple mistakes sharing one failure mode → ONE lesson.
6455. **Recurrence gate:** "Would this recur in future session WITHOUT this reminder?" — No → skip `$learn`.
6466. **Auto-fix gate:** "Could `$code-review`/`$code-simplifier`/`$security-review`/`$lint` catch this?" — Yes → improve review skill instead.
6477. BOTH gates pass → ask user to run `$learn`.
648 **[CRITICAL-THINKING-MINDSET]** Apply critical thinking, sequential thinking. Every claim needs traced proof, confidence >80% to act.
649 **Anti-hallucination principle:** Never present guess as fact — cite sources for every claim, admit uncertainty freely, self-check output for errors, cross-reference independently, stay skeptical of own confidence — certainty without evidence root of all hallucination.
650 **AI Attention principle (Primacy-Recency):** Put the 3 most critical rules at both top and bottom of long prompts/protocols so instruction adherence survives long context windows.
651 **Goal-driven execution:** Define success criteria first, loop until verified, and stop only when observable checks pass.
652 **Tests verify intent:** Tests must protect business rules/invariants and fail when the protected intent breaks, not only mirror current behavior.
653
654## Common AI Mistake Prevention (System Lessons)
655
656- **Re-read files after context compaction.** Edit requires prior Read in same context; compaction wipes read state. Re-read before editing.
657- **Grep for old terms after bulk replacements.** AI over-trusts find/replace completeness. Grep full repo after bulk edits for missed refs in docs/configs/catalogs.
658- **Check downstream references before deleting.** Deletions cascade doc/code staleness. Map referencing files before removal.
659- **After memory loss, check existing state before creating new.** Compaction wipes prior-work memory. Query current state to resume — never blindly duplicate.
660- **Verify AI-generated content against actual code.** AI hallucinates APIs, class names, method signatures. Grep to confirm existence before documenting/referencing.
661- **Trace full dependency chain after edits.** Changing a definition misses downstream consumers. Trace the full chain.
662- **When renaming, grep ALL consumer file types.** Some file types silently ignore missing refs (no compile error). Search code, templates, configs, generated files.
663- **Trace ALL code paths when verifying correctness.** Code existing ≠ code executing. Trace early exits, error branches, conditional skips — not just happy path.
664- **Update docs that embed canonical data when source changes.** Docs inlining derived data (workflows, schemas, configs) go stale silently. Update all embedding docs alongside source.
665- **Verify sub-agent results after context recovery.** Background agents may finish while parent compacted — grep-verify output, don't trust assumed completion.
666- **Cross-check full target list against sub-agent assignments.** Parallel sub-agents by category miss boundary items. Reconcile union of assignments against target list before proceeding.
667- **Sub-agents inherit knowledge only from their agent .md definition — use custom agent types, not built-in Explore.** Tool adoption = permission + knowledge + enforcement (numbered workflow step).
668- **Persist sub-agent findings incrementally, not as a final batch.** Long sub-agents hit cutoffs before final write — findings lost. Instruct append-per-section to report file.
669- **When debugging, ask "whose responsibility?" before fixing.** Trace caller (wrong data) vs callee (wrong handling). Fix at responsible layer — never patch symptom site.
670- **Test failure → record a provisional verdict before trace/edit, then investigate.** Use the full five-way taxonomy: SOURCE-WRONG (production violates intent), TEST-WRONG (assertion/setup is stale), TEST-NOT-OPTIMAL (valid but fragile or low-signal test), ENVIRONMENT-BLOCKED (external state prevents a verdict), or AMBIGUOUS (intent/evidence cannot choose safely). Then trace root cause and triangulate against the governing spec (`docs/specs/**` if one exists) AND source. NEVER weaken an assertion, add a skip, relax a timeout, or change source merely to force green.
671- **Grep ALL removed names after extraction/refactoring.** Primary file "done" ≠ secondary files clean. Grep entire scope for every removed symbol before declaring complete.
672- **Assume existing values are intentional — ask WHY before changing OR flagging one as a defect.** Pattern-matching as "wrong" skips context. Before changing or reporting any constant/limit/flag/cutoff: read comments, git blame, the CALLER's ordering (the guarantee that makes the value correct usually lives in code running immediately BEFORE the cited line), and 2+ sibling call sites of the same convention. A doc stating WHAT without WHY is missing rationale, not proof of a missing guard — and in a validation pass, an accurate `file:line` citation proves the transcription, never the defect.
673- **Verify ALL affected outputs, not just the first.** One build green ≠ all green. Multi-stack changes (backend/frontend/tests/docs) require verifying EVERY output.
674- **Evaluate fit before copying a nearby pattern.** Closest example ≠ matching preconditions — verify the new context shares the same constraints, base classes, scope, lifetime.
675- **Holistic-first debugging — resist nearest-attention trap.** Don't dive into first plausible cause. List EVERY precondition (config, env vars, paths, DB, endpoints, creds, versions, DI, data). Verify each against evidence (grep/query — not reasoning). Ask "what would falsify this?" — if nothing, it's not a hypothesis. Most expensive failure: going deeper in "obvious" layer while bug sits in layer never questioned.
676- **Surgical changes — apply the diff test (context-aware).** Two modes: (1) Bug fix → every line traces to the bug; no restyling; orphan cleanup only for imports YOUR changes made unused. (2) Review/enhancement → implement improvements AND announce as "Enhancement beyond main request: [what]". Never silently scope-creep. Diff test: "Would this line exist if I wasn't asked to do X?" — if no, delete or announce.
677- **Surface ambiguity before coding — don't pick silently.** Multiple valid interpretations → present each with effort: "[Request] could mean (1) [N h], (2) [N h]. Which matters?" List scope/format/volume/constraints assumptions first. If simpler path exists, say so. Never silently pick.
678- **[MANDATORY FIRST ACTION] ALWAYS activate a suitable skill or workflow BEFORE responding.** Match task against workflow catalog + skill list; invoke via skill invocation or `$start-workflow <workflowId>`. NEVER answer or write code before checking. Skip = protocol violation.
679- **Why-Review adversarial mindset — apply when reviewing any plan, decision, or design.** Default SKEPTIC not VALIDATOR: steel-man a rejected alternative, invert each stated reason ("what does it sacrifice?"), stress-test top 2-3 assumptions, run pre-mortem ("ships, fails in 3 months — what breaks?"), surface 1-2 alternatives author missed. Section presence ≠ quality; quality = causal reasoning + concrete mitigations + evidence, not "it's better" or "monitor closely".
680- **Front-load report-write in sub-agent prompts for large reviews.** Many-file sub-agents hit budget before final write — findings lost. Design prompts so: (1) report-write is first explicit deliverable, (2) append per-file/section (not batched), (3) scope bounded so reads don't exhaust budget. Truncated mid-sentence with no report file → spawn narrower scope, don't retry same prompt.
681- **After context compaction, re-verify all prior phase outcomes before continuing.** Summaries describe intent, not environment state (git index, filesystem, processes). On resume, FIRST audit: git status, re-read modified files, verify filesystem. Every "completed" claim is an untested hypothesis until evidence confirms.
682- **OOM/memory: check row count before row size.** Triage: (1) Unbounded query — no DB filter for trigger? Push filter to DB; eliminates OOM. (2) Large rows? Projection reduces proportionally. Row reduction > projection in ROI.
683- **Assert the outcome your system OWNS, never the intermediate state your INFRASTRUCTURE owns.** When testing anything asynchronous (queue/broker delivery, retries, background jobs, caches, replication), assert the final business/entity state. NEVER assert the delivery bookkeeping — consume/send status, attempt counts, last-error, row existence or counts in a broker, scheduler, or outbox/inbox table. That bookkeeping lives in shared infrastructure that ANY co-running process (a peer worker, a second replica, a leftover local container) can write, usually under a deterministic shared key, so the assertion silently tests the developer's environment instead of the system: green when run alone, flaky the instant anything else shares that broker + database. Gate question for every assertion: "would this hold no matter WHICH process did the work?" — if no, assert the converged data state instead. Corollary: process-local fault injection and in-process telemetry cannot gate work any process may perform — use them as stress amplifiers (arm → bounded window → disarm → assert convergence), never as preconditions.
684- **Keep domain concepts out of generic/shared/infrastructure layers.** Reusable layer (shared library, framework, infra module) must reference NO consumer-specific domain concept — tenant/customer/product IDs, business entities, feature rules. Leak compiles + runs → passes review silently while coupling the "reusable" layer to one consumer. Keep shared type domain-free; push domain fields/logic down into the consumer via subclass/composition. — why: a layer coupled to one consumer's domain is no longer reusable.
685
686<!-- CODEX:SYNC-PROMPT-PROTOCOLS:END -->