Agent Skills: Lessons Learned

Codex compatibility note:

• Invoke repository skills with $skill-name in Codex; this mirrored copy rewrites legacy Claude /skill-name references.
• Prefer the plan-hard skill for planning guidance in this Codex mirror.
• 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 does not receive Claude hook-based doc injection. 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)

Situation-based docs:

• Backend/CQRS/API/domain/entity changes: backend-patterns-reference.md, domain-entities-reference.md, project-structure-reference.md
• Frontend/UI/styling/design-system: frontend-patterns-reference.md, scss-styling-guide.md, design-system/README.md
• Spec/test-case planning or TC mapping: feature-docs-reference.md
• 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: READ-ONLY exploration — understand how code works, zero changes.

Workflow:

1. Phase 0: Classify — Determine scope (quick / deep / debug / recommendation) before acting
2. Discovery — Search codebase for related files (Entities > Commands > Events > Controllers)
3. Graph Expand — Run graph queries on 2-3 key files (MANDATORY, main agent only)
4. Knowledge Graph — Read + document purpose, symbols, dependencies per file
5. Flow Mapping — Trace entry points through pipeline to exit points
6. Analysis — Extract business rules, validation, authorization, error handling
7. Synthesis — Write executive summary to .ai/workspace/analysis/[feature]-investigation.md
8. Present — Deliver structured findings, offer deeper dives

Key Rules:

• Strictly READ-ONLY — NEVER make code changes
• Every claim needs file:line proof — mark unverified as "inferred"
• MUST ATTENTION run at least ONE graph command on key files before concluding
• MUST ATTENTION Plan ToDo Task to READ project-structure-reference.md (if not found, search: project documentation, coding standards, architecture docs)

Phase 0: Scope Classification

Classify before acting — route to correct depth:

| Scope | Signals | Depth | | ------------------ | ---------------------------------------------- | -------------------------------------------------------- | | Quick | Single feature/function, clear entry point | grep → trace → answer (no analysis file needed) | | Deep | Multi-service, cross-boundary, ambiguous scope | Full workflow + knowledge graph template + analysis file | | Debug | Error/crash/unexpected behavior | Root-cause-debugging protocol above | | Recommendation | Code change suggested (removal, refactor) | Validation chain protocol below — MANDATORY |

Quick scope: Skip knowledge graph template + analysis file. Grep → graph trace → present findings. Deep scope: MUST ATTENTION write to .ai/workspace/analysis/[feature]-investigation.md.

Investigation Mindset (NON-NEGOTIABLE)

Skeptical. Every claim needs file:line traced proof. Confidence >80% to act.

• NEVER assume code works as named — verify by reading actual implementations
• MUST ATTENTION include file:line for every finding; unproven claims MUST ATTENTION be marked "inferred"
• ALWAYS grep related usages, consumers, cross-service references — NEVER assume completeness
• ALWAYS trace actual call paths with evidence — NEVER rely on signatures alone

Workflow

1. Discovery — Search for all related files. Priority: Entities > Commands/Queries > EventHandlers > Controllers > Consumers > Components.

2. Graph Expand (MANDATORY — DO NOT SKIP) — YOU (main agent) MUST ATTENTION run graph queries YOURSELF on key files from Step 1. Sub-agents CANNOT use graph — only you can. Pick 2-3 key files (entities, commands, bus messages):

   python .claude/scripts/code_graph connections <key_file> --json
   python .claude/scripts/code_graph query callers_of <FunctionName> --json
   python .claude/scripts/code_graph query importers_of <file_path> --json
   # "ambiguous" → search to disambiguate, retry with qualified name
   python .claude/scripts/code_graph search <keyword> --kind Function --json
   # Trace how two nodes connect
   python .claude/scripts/code_graph find-path <source> <target> --json
   # Filter by service, limit results
   python .claude/scripts/code_graph query callers_of <name> --limit 5 --filter "ServiceName" --json
   

   Graph reveals complete dependency network (callers, importers, tests, inheritance) grep alone misses. Also run $graph-connect-api for frontend-to-backend API mapping.

3. Knowledge Graph — Read + analyze each file (from grep + graph results). Document purpose, symbols, dependencies, data flow. Batch in groups of 10; update progress after each batch. Per-file template:

4. Flow Mapping — Trace entry points through processing pipeline to exit points. Map data transformations, persistence, side effects, cross-service boundaries.

5. Analysis — Extract business rules, validation, authorization, error handling. Document happy path AND edge cases.

6. Synthesis — Executive summary answering original question. Key files, patterns used, text-based flow diagrams.

7. Present — Structured output (see Output Format). Offer deeper dives on subtopics.

If preceded by $scout: Use Scout's numbered file list as analysis targets. Skip redundant discovery. Prioritize HIGH PRIORITY files.

Investigation Techniques

Discovery Search Patterns

Grep {FeatureName} combined with: EventHandler, BackgroundJob, Consumer, Service, Component.

Priority order: (1) Entities → (2) Commands/Queries (UseCaseCommands/) → (3) Event Handlers (UseCaseEvents/) → (4) Controllers → (5) Consumers (*BusMessage.cs) → (6) Background Jobs → (7) Components/Stores → (8) Services/Helpers

Dependency Tracing

Backend: method callers (grep *.cs), service injectors (grep interface in constructors), entity events (EntityEvent<Name>), cross-service (*BusMessage across services), repository usage (IRepository<Name>).

Frontend: component users (grep selector in *.html), service importers (grep class in *.ts), store chains (effectSimple → API → tapResponse → state), routes (grep component in *routing*.ts).

Data Flow Mapping

Document as: [Entry] → [Validation] → [Processing] → [Persistence] → [Side Effects]

MUST ATTENTION trace: (1) Entry points, (2) Processing pipeline, (3) Data transformations, (4) Persistence points, (5) Exit points/responses, (6) Cross-service message bus boundaries.

Common Investigation Scenarios

| Question Type | Steps | | --------------------------- | --------------------------------------------------------------------------------------- | | "How does X work?" | Entry points → command/query handlers → entity changes → side effects | | "Where is logic for Y?" | Keywords in commands/queries/entities → event handlers → helpers → frontend stores | | "What happens when Z?" | Identify trigger → trace handler chain → document side effects + error handling | | "Why does A behave like B?" | Find code path → identify decision points → check config/feature flags → document rules |

Project Pattern Recognition

Backend (search for backend-patterns-reference in docs/): CQRS commands/queries, entity event handlers, message bus consumers, repository extensions, validation fluent API, authorization attributes.

Frontend (search for frontend-patterns-reference in docs/): store component base, store base, effectSimple/tapResponse, observerLoadingErrorState, API service base class.

Graph Intelligence (MANDATORY when graph.db exists)

MUST ATTENTION orchestrate grep → graph → grep dynamically: (1) Grep key terms to find entry files, (2) Use connections/batch-query/trace --direction both to expand dependency network, (3) Grep again to verify content. trace follows ALL edge types including MESSAGE_BUS and TRIGGERS_EVENT.

python .claude/scripts/code_graph connections <file> --json     # Full picture
python .claude/scripts/code_graph query callers_of <name> --json
python .claude/scripts/code_graph query importers_of <file> --json
python .claude/scripts/code_graph query tests_for <name> --json
python .claude/scripts/code_graph batch-query <f1> <f2> --json

Evidence Collection

Deep scope — MANDATORY: Write analysis to .ai/workspace/analysis/[feature-name]-investigation.md. MUST ATTENTION re-read ENTIRE file before presenting findings.

Structure: Metadata (original question) → Progress → File List → Knowledge Graph (per-file entries per SYNC:knowledge-graph-template) → Data Flow → Findings.

Rule: Every 10 files → MUST ATTENTION update progress, re-check alignment with original question.

Analysis Phases

Comprehensive: (1) Happy path, (2) Error paths, (3) Edge cases, (4) Authorization checks, (5) Validation per layer. Extract: core business rules, state transitions, side effects.

Synthesis: Executive summary (1-para answer, top 5-10 key files, patterns used) + step-by-step walkthrough with file:line references + flow diagrams.

Output Format

MUST ATTENTION include: (1) Direct answer (1-2 paragraphs), (2) Step-by-step "How It Works" with file:line refs, (3) Key Files table, (4) Data Flow diagram, (5) "Want to Know More?" subtopics.

Guidelines

• Evidence-based — every claim needs code evidence; MUST ATTENTION mark unverified as "inferred"
• Question-focused — ALWAYS tie findings back to original question
• Read-only — NEVER suggest changes unless explicitly asked
• Layered — Start simple, offer deeper detail on request

Related Skills

scout (pre-discovery) | feature (implementation) | debug-investigate (debugging) | graph-query (natural language queries)

Investigation & Recommendation Protocol

Applies when recommending code changes (removal, refactoring, replacement). MUST ATTENTION complete full validation chain.

Validation Chain (NEVER skip steps)

NEVER recommend code changes without completing ALL steps:

1. Interface/API identified → 2. ALL implementations found → 3. ALL registrations traced → 4. ALL usage sites verified → 5. Cross-service impact (ALL services) → 6. Impact assessment → 7. Confidence declaration → ONLY THEN output recommendation.

If ANY step incomplete → STOP. State "Insufficient evidence to recommend."

Breaking Change Risk Matrix

| Risk | Criteria | Required Evidence | | ---------- | ------------------------------------------------------------- | -------------------------------------------------------------- | | HIGH | Removing registrations, deleting classes, changing interfaces | Full usage trace + impact + cross-service check (all services) | | MEDIUM | Refactoring methods, changing signatures | Usage trace + test verification + cross-service check | | LOW | Renaming variables, formatting, comments | Code review only |

Removal Checklist (ALL MUST ATTENTION pass)

• [ ] No static references (grep -r "ClassName" --include="*.cs" = 0)
• [ ] No string literals / dynamic invocations (reflection, factory, message bus)
• [ ] No DI registrations (services.Add*<ClassName>)
• [ ] No config references (appsettings, env vars)
• [ ] No test dependencies
• [ ] Cross-service impact checked (ALL microservices)

Incomplete checklist → state: Confidence: <90% — did not verify [missing items]

Evidence Hierarchy

(1) Code evidence (grep/read) → (2) Test evidence → (3) Documentation → (4) Inference. Recommendations based on inference alone FORBIDDEN — MUST ATTENTION upgrade to code evidence.

Confidence Levels

95-100% full trace + all services | 80-94% main paths verified | 60-79% partially traced | <60% DO NOT RECOMMEND

Format: Confidence: 85% — Verified main usage in ServiceC, did not check ServiceA/ServiceB

Service Comparison Pattern

Find working reference → compare implementations → identify differences → verify WHY each difference exists → recommend based on proven pattern, NEVER assumptions.

[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 (when task involves business entities/models). (read directly when relevant; do not rely on hook-injected conversation text)

> **Knowledge Graph Template** — For each analyzed file, document: filePath, type (Entity/Command/Query/EventHandler/Controller/Consumer/Component/Store/Service), architecturalPattern, content summary, symbols, dependencies, businessContext, referenceFiles, relevanceScore (1-10), evidenceLevel (verified/inferred), frameworkAbstractions, serviceContext. Investigation fields: entryPoints, outputPoints, dataTransformations, errorScenarios. Consumer/bus fields: messageBusMessage, messageBusProducers, crossServiceIntegration. Frontend fields: componentHierarchy, stateManagementStores, dataBindingPatterns, validationStrategies.

Root Cause Debugging — Systematic approach, never guess-and-check.

1. Reproduce — Confirm issue exists with evidence (error message, stack trace, screenshot)
2. Isolate — Narrow to specific file/function/line using binary search + graph trace
3. Trace — Follow data flow from input to failure point. Read actual code, don't infer.
4. Hypothesize — Form theory with confidence %. State what evidence supports/contradicts it
5. Verify — Test hypothesis with targeted grep/read. One variable at a time.
6. Fix — Address root cause, not symptoms. Verify fix doesn't break callers via graph connections

NEVER: Guess without evidence. Fix symptoms instead of cause. Skip reproduction step.

Nested Task Expansion Contract — For workflow-step invocation, the [Workflow] ... row is only a parent container; the child skill still creates visible phase tasks.

1. Call the current task list first. If a matching active parent workflow row exists, set nested=true and record parentTaskId; otherwise run standalone.
2. Create one task per declared phase before phase work. When nested, prefix subjects [N.M] $skill-name — phase.
3. When nested, link the parent with TaskUpdate(parentTaskId, addBlockedBy: [childIds]).
4. Orchestrators must pre-expand a child skill's phase list and link the workflow row before invoking that child skill or sub-agent.
5. Mark exactly one child in_progress before work and completed immediately after evidence is written.
6. 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.

1. Identify scope: file types, domain area, and operation.
2. 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-docs-reference.md; architecture/new area project-structure-reference.md.
3. Read every required doc that exists; skip absent docs as not applicable. Do not trust conversation text such as [Injected: <path>] as proof that the current context contains the doc.
4. Before target work, state: Reference docs read: ... | Missing/not applicable: ....

Blocked until: scope evaluated, required docs checked/read, lessons.md confirmed, citation emitted.

Task Tracking & External Report Persistence — Bootstrap this before execution; then run project-reference doc prefetch before target/source work.

1. Create a small task breakdown before target file reads, grep, edits, or analysis. On context loss, inspect the current task list first.
2. Mark one task in_progress before work and completed immediately after evidence; never batch transitions.
3. For plan/review work, create plans/reports/{skill}-{YYMMDD}-{HHmm}-{slug}.md before first finding.
4. Append findings after each file/section/decision and synthesize from the report file at the end.
5. Final output cites Full report: plans/reports/{filename}.

Blocked until: task breakdown exists, report path declared for plan/review work, first finding persisted before the next finding.

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.

Sequential Thinking Protocol — Structured multi-step reasoning for complex/ambiguous work. Use when planning, reviewing, debugging, or refining ideas where one-shot reasoning is unsafe.

Trigger when: complex problem decomposition · adaptive plans needing revision · analysis with course correction · unclear/emerging scope · multi-step solutions · hypothesis-driven debugging · cross-cutting trade-off evaluation.

Format (explicit mode — visible thought trail):

1. Thought N/M: [aspect] — one aspect per thought, state assumptions/uncertainty
2. Thought N/M [REVISION of Thought K]: ... — when prior reasoning invalidated; state Original / Why revised / Impact
3. Thought N/M [BRANCH A from Thought K]: ... — explore alternative; converge with decision rationale
4. Thought N/M [HYPOTHESIS]: ... then [VERIFICATION]: ... — test before acting
5. Thought N/N [FINAL] — only when verified, all critical aspects addressed, confidence >80%

Mandatory closers: Confidence % stated · Assumptions listed · Open questions surfaced · Next action concrete.

Stop conditions: confidence <80% on any critical decision → escalate via ask the user directly · ≥3 revisions on same thought → re-frame the problem · branch count >3 → split into sub-task.

Implicit mode: apply methodology internally without visible markers when adding markers would clutter the response (routine work where reasoning aids accuracy).

Deep-dive: see $sequential-thinking skill (.claude/skills/sequential-thinking/SKILL.md) for worked examples (api-design, debug, architecture), advanced techniques (spiral refinement, hypothesis testing, convergence), and meta-strategies (uncertainty handling, revision cascades).

Understand Code First — HARD-GATE: Do NOT write, plan, or fix until you READ existing code.

1. Search 3+ similar patterns (grep/glob) — cite file:line evidence
2. Read existing files in target area — understand structure, base classes, conventions
3. Run python .claude/scripts/code_graph trace <file> --direction both --json when .code-graph/graph.db exists
4. Map dependencies via connections or callers_of — know what depends on your target
5. Write investigation to .ai/workspace/analysis/ for non-trivial tasks (3+ files)
6. Re-read analysis file before implementing — never work from memory alone
7. NEVER invent new patterns when existing ones work — match exactly or document deviation

BLOCKED until: - [ ] Read target files - [ ] Grep 3+ patterns - [ ] Graph trace (if graph.db exists) - [ ] Assumptions verified with evidence

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.

Cross-Service Check — Microservices/event-driven: MANDATORY before concluding investigation, plan, spec, or feature doc. Missing downstream consumer = silent regression.

| Boundary | Grep terms | | ------------------- | ------------------------------------------------------------------------------- | | Event producers | Publish, Dispatch, Send, emit, EventBus, outbox, IntegrationEvent | | Event consumers | Consumer, EventHandler, Subscribe, @EventListener, inbox | | Sagas/orchestration | Saga, ProcessManager, Choreography, Workflow, Orchestrator | | Sync service calls | HTTP/gRPC calls to/from other services | | Shared contracts | OpenAPI spec, proto, shared DTO — flag breaking changes | | Data ownership | Other service reads/writes same table/collection → Shared-DB anti-pattern |

Per touchpoint: owner service · message name · consumers · risk (NONE / ADDITIVE / BREAKING).

BLOCKED until: Producers scanned · Consumers scanned · Sagas checked · Contracts reviewed · Breaking-change risk flagged

Fix-Layer Accountability — NEVER fix at the crash site. Trace the full flow, fix at the owning layer.

AI default behavior: see error at Place A → fix Place A. This is WRONG. The crash site is a SYMPTOM, not the cause.

MANDATORY before ANY fix:

1. Trace full data flow — Map the complete path from data origin to crash site across ALL layers (storage → backend → API → frontend → UI). Identify where the bad state ENTERS, not where it CRASHES.
2. Identify the invariant owner — Which layer's contract guarantees this value is valid? That layer is responsible. Fix at the LOWEST layer that owns the invariant — not the highest layer that consumes it.
3. One fix, maximum protection — Ask: "If I fix here, does it protect ALL downstream consumers with ONE change?" If fix requires touching 3+ files with defensive checks, you are at the wrong layer — go lower.
4. Verify no bypass paths — Confirm all data flows through the fix point. Check for: direct construction skipping factories, clone/spread without re-validation, raw data not wrapped in domain models, mutations outside the model layer.

BLOCKED until: - [ ] Full data flow traced (origin → crash) - [ ] Invariant owner identified with file:line evidence - [ ] All access sites audited (grep count) - [ ] Fix layer justified (lowest layer that protects most consumers)

Anti-patterns (REJECT these):

• "Fix it where it crashes" — Crash site ≠ cause site. Trace upstream.
• "Add defensive checks at every consumer" — Scattered defense = wrong layer. One authoritative fix > many scattered guards.
• "Both fix is safer" — Pick ONE authoritative layer. Redundant checks across layers send mixed signals about who owns the invariant.

AI Mistake Prevention — Failure modes to avoid on every task:

Check downstream references before deleting. Deleting components causes documentation and code staleness cascades. Map all referencing files before removal. Verify AI-generated content against actual code. AI hallucinates APIs, class names, and method signatures. Always grep to confirm existence before documenting or referencing. Trace full dependency chain after edits. Changing a definition misses downstream variables and consumers derived from it. Always trace the full chain. Trace ALL code paths when verifying correctness. Confirming code exists is not confirming it executes. Always trace early exits, error branches, and conditional skips — not just happy path. When debugging, ask "whose responsibility?" before fixing. Trace whether bug is in caller (wrong data) or callee (wrong handling). Fix at responsible layer — never patch symptom site. Assume existing values are intentional — ask WHY before changing. Before changing any constant, limit, flag, or pattern: read comments, check git blame, examine surrounding code. Verify ALL affected outputs, not just the first. Changes touching multiple stacks require verifying EVERY output. One green check is not all green checks. Holistic-first debugging — resist nearest-attention trap. When investigating any failure, list EVERY precondition first (config, env vars, DB names, endpoints, DI registrations, data preconditions), then verify each against evidence before forming any code-layer hypothesis. Surgical changes — apply the diff test. Bug fix: every changed line must trace directly to the bug. Don't restyle or improve adjacent code. Enhancement task: implement improvements AND announce them explicitly. Surface ambiguity before coding — don't pick silently. If request has multiple interpretations, present each with effort estimate and ask. Never assume all-records, file-based, or more complex path.

• MANDATORY IMPORTANT MUST ATTENTION search 3+ existing patterns and read code BEFORE any modification. Run graph trace when graph.db exists. <!-- /SYNC:understand-code-first:reminder -->

• MANDATORY IMPORTANT MUST ATTENTION run at least ONE graph command on key files when graph.db exists. Pattern: grep → graph trace → grep verify. <!-- /SYNC:graph-assisted-investigation:reminder -->

• MANDATORY IMPORTANT MUST ATTENTION cite file:line evidence for every claim. Confidence >80% to act, <60% = do NOT recommend. <!-- /SYNC:evidence-based-reasoning:reminder -->

• MANDATORY IMPORTANT MUST ATTENTION document per-file: type, pattern, symbols, dependencies, relevanceScore, evidenceLevel. <!-- /SYNC:knowledge-graph-template:reminder -->

IMPORTANT MUST ATTENTION trace full data flow and fix at the owning layer, not the crash site. Audit all access sites before adding ?..

MUST ATTENTION apply critical thinking — every claim needs traced proof, confidence >80% to act. Anti-hallucination: never present guess as fact.

MUST ATTENTION apply sequential-thinking — multi-step Thought N/M, REVISION/BRANCH/HYPOTHESIS markers, confidence % closer; see $sequential-thinking skill.

MUST ATTENTION apply AI mistake prevention — holistic-first debugging, fix at responsible layer, surface ambiguity before coding, re-read files after compaction.

• MANDATORY Bootstrap task tracking before target work; transition one task at a time.
• MANDATORY Persist plan/review findings to plans/reports/ incrementally and synthesize from disk.

• MANDATORY After task-tracking bootstrap and before target/source work, read required project-reference docs and cite Reference docs read: ....
• MANDATORY Always include lessons.md; project conventions override generic defaults.

• 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.

Closing Reminders

• MANDATORY IMPORTANT MUST ATTENTION break work into small todo tasks using task tracking BEFORE starting
• MANDATORY IMPORTANT MUST ATTENTION Phase 0: classify scope (quick/deep/debug/recommendation) before acting
• MANDATORY IMPORTANT MUST ATTENTION cite file:line evidence for every claim (confidence >80% to act, <60% DO NOT recommend)
• MANDATORY IMPORTANT MUST ATTENTION run at least ONE graph command on key files before concluding any investigation
• MANDATORY IMPORTANT MUST ATTENTION deep scope → write analysis to .ai/workspace/analysis/[feature]-investigation.md; re-read ENTIRE file before presenting
• MANDATORY IMPORTANT MUST ATTENTION recommendation scope → complete ALL validation chain steps before any code change suggestion

Anti-Rationalization:

| Evasion | Rebuttal | | -------------------------------------------------- | ------------------------------------------------------------------------- | | "Simple investigation, skip graph" | Graph reveals callers + bus consumers grep misses. Run it anyway. | | "Already grepped, enough evidence" | Show file:line proof. No citation = no evidence. | | "Quick task, skip task tracking" | Still need tracking. Create tasks, mark done immediately. | | "Recommendation is obvious, skip validation chain" | Risk matrix applies regardless of confidence. Complete ALL steps. | | "Deep scope wastes time for this" | Classify first. If quick, fine — but DECLARE scope before skipping steps. |

[TASK-PLANNING] Before acting, analyze task scope and systematically break it into small todo tasks and sub-tasks using task tracking.

Hookless Prompt Protocol Mirror (Auto-Synced)

Source: .claude/hooks/lib/prompt-injections.cjs + .claude/.ck.json

[WORKFLOW-EXECUTION-PROTOCOL] [BLOCKING] Workflow Execution Protocol — MANDATORY IMPORTANT MUST CRITICAL. Do not skip for any reason.

1. DETECT: Match prompt against workflow catalog
2. ANALYZE: Find best-match workflow AND evaluate if a custom step combination would fit better
3. ASK (REQUIRED FORMAT): Use a direct user question with this structure:
   • Question: "Which workflow do you want to activate?"
   • Option 1: "Activate [BestMatch Workflow] (Recommended)"
   • Option 2: "Activate custom workflow: [step1 → step2 → ...]" (include one-line rationale)
4. ACTIVATE (if confirmed): Call $workflow-start <workflowId> for standard; sequence custom steps manually
5. CREATE TASKS: task tracking for ALL workflow steps
6. EXECUTE: Follow each step in sequence [CRITICAL-THINKING-MINDSET] Apply critical thinking, sequential thinking. Every claim needs traced proof, confidence >80% to act. 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. 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.

Learned Lessons

Lessons Learned

[CRITICAL] Hard-won project debugging/architecture rules. MUST ATTENTION apply BEFORE forming hypothesis or writing code.

Quick Summary

Goal: Prevent recurrence of known failure patterns — debugging, architecture, naming, AI orchestration, environment.

Top Rules (apply always):

• MUST ATTENTION verify ALL preconditions (config, env, DB names, DI regs) BEFORE code-layer hypothesis
• MUST ATTENTION fix responsible layer — NEVER patch symptom sites with caller-specific defensive code
• MUST ATTENTION use ExecuteInjectScopedAsync for parallel async + repo/UoW — NEVER ExecuteUowTask
• MUST ATTENTION name by PURPOSE not CONTENT — adding member forces rename = abstraction broken
• MUST ATTENTION persist sub-agent findings incrementally after each file — NEVER batch at end
• MUST ATTENTION Windows bash: verify Python alias (where python/where py) — NEVER assume python/python3 resolves

Debugging & Root Cause Reasoning

• [2026-04-11] Holistic-first: verify environment before code. Failure → list ALL preconditions (config, env vars, DB names, endpoints, DI regs, credentials, permissions, data prerequisites) → verify each via evidence (grep/cat/query) BEFORE code-layer hypothesis. Worst rabbit holes: diving nearest layer while bug sits elsewhere — e.g., hours debugging "sync timeout", real cause: test appsettings pointing wrong DB. ALWAYS cheapest check first.
• [2026-04-01] Ask "whose responsibility?" before fixing. Trace: bug caller (wrong data) or callee (wrong handling)? Fix responsible layer — NEVER patch symptom site masking real issue.
• [2026-04-01] Trace data lifecycle, not error site. Follow data: creation → transformation → consumption. Bug usually where data created wrong, not consumed.
• [2026-04-01] Code caller-agnostic. Functions/handlers/consumers don't know who invokes them. Comments/guards/messages describe business intent — NEVER reference specific callers (tests, seeders, scripts).

Architecture Invariants

• [2026-05-09] User name materialization MUST ATTENTION go through User.UpdateName(firstName, middleName, lastName). Domain method (src/Services/bravoTALENTS/Employee.Domain/AggregatesModel/User.cs:202-209) recomputes FullName as single source of truth. Three sites still manually patch user.FullName = user.GetFullName() after assigning name fields — src/Services/bravoTALENTS/Employee.Application/Factories/UserFactory.cs:50, src/Services/bravoSURVEYS/LearningPlatform.Application/ApplyPlatform/MessageBus/Consumers/AccountUserDeletedEventBusConsumer.cs:102, src/Services/bravoINSIGHTS/Analyze/Analyze.Application/MessageBus/Consumers/AccountUserDeletedEventBusConsumer.cs:66. Next time touching any: replace manual patch with user.UpdateName(...) to maintain invariant.
• [2026-03-31] ParallelAsync + repo/UoW MUST ATTENTION use ExecuteInjectScopedAsync, NEVER ExecuteUowTask. ExecuteUowTask creates new UoW but reuses outer DI scope (same DbContext) — parallel iterations sharing non-thread-safe DbContext silently corrupt data. ExecuteInjectScopedAsync creates new UoW + new DI scope (fresh repo per iteration).
• [2026-03-31] Bus message naming MUST ATTENTION include service name prefix — core services NEVER consume feature events. Prefix declares schema ownership (AccountUserEntityEventBusMessage = Accounts owns). Core services (Accounts, Communication) leaders. Feature services (Growth, Talents) sending to core MUST ATTENTION use {CoreServiceName}...RequestBusMessage — NEVER define own event for core to consume.

Naming & Abstraction

• [2026-04-12] Name PURPOSE not CONTENT — "OrXxx" anti-pattern. HrManagerOrHrOrPayrollHrOperationsPolicy names set members, not what guards. Add role → rename = broken abstraction. Rule: names express DOES/GUARDS, not CONTAINS. Test: adding/removing member forces rename? YES = content-driven = bad → rename to purpose (e.g., HrOperationsAccessPolicy). Nuance: "Or" fine behavioral idioms (FirstOrDefault, SuccessOrThrow) — expresses HAPPENS, not membership.

Environment & Tooling

• [2026-04-20] Windows bash: NEVER assume python/python3 resolves — verify alias first. Python may not be bash PATH under those names. Check: where python / where py. ALWAYS prefer py (Windows Python Launcher) one-liners, node if JS alternative exists.

Test-specific lessons → docs/project-reference/integration-test-reference.md Lessons Learned section. Production-code anti-patterns → docs/project-reference/backend-patterns-reference.md Anti-Patterns section. Generic debugging/refactoring reminders → System Lessons .claude/hooks/lib/prompt-injections.cjs.

Closing Reminders

• IMPORTANT MUST ATTENTION holistic-first: verify ALL preconditions (config, env, DB names, endpoints, DI regs) BEFORE code-layer hypothesis — cheapest check first
• IMPORTANT MUST ATTENTION fix responsible layer — NEVER patch symptom site; trace caller (wrong data) vs callee (wrong handling), fix root owner
• IMPORTANT MUST ATTENTION parallel async + repo/UoW → ALWAYS ExecuteInjectScopedAsync, NEVER ExecuteUowTask (shared DbContext = silent data corruption)
• IMPORTANT MUST ATTENTION bus message prefix = schema ownership; feature services NEVER define events for core services — use {CoreServiceName}...RequestBusMessage
• IMPORTANT MUST ATTENTION name by PURPOSE — adding/removing member forces rename = broken abstraction
• IMPORTANT MUST ATTENTION sub-agents MUST write findings after each file/section — NEVER batch all findings into one final write
• IMPORTANT MUST ATTENTION Windows bash: NEVER assume python/python3 resolves — run where python/where py first, use py launcher or node
• IMPORTANT MUST ATTENTION every claim needs file:line evidence — confidence >80% to act, NEVER speculate

[LESSON-LEARNED-REMINDER] [BLOCKING] Task Planning & Continuous Improvement — MANDATORY. Do not skip.

Break work into small tasks (task tracking) before starting. Add final task: "Analyze AI mistakes & lessons learned".

Extract lessons — ROOT CAUSE ONLY, not symptom fixes:

1. Name the FAILURE MODE (reasoning/assumption failure), not symptom — "assumed API existed without reading source" not "used wrong enum value".
2. Generality test: does this failure mode apply to ≥3 contexts/codebases? If not, abstract one level up.
3. Write as a universal rule — strip project-specific names/paths/classes. Useful on any codebase.
4. Consolidate: multiple mistakes sharing one failure mode → ONE lesson.
5. Recurrence gate: "Would this recur in future session WITHOUT this reminder?" — No → skip $learn.
6. Auto-fix gate: "Could $code-review/$code-simplifier/$security/$lint catch this?" — Yes → improve review skill instead.
7. BOTH gates pass → ask user to run $learn. [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.