Feature Investigation

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:START -->

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.

<!-- CODEX:PROJECT-REFERENCE-LOADING:END -->

<!-- PROMPT-ENHANCE:STEP-TASK-ANCHOR:START -->

[BLOCKING] Execute skill steps in declared order. NEVER skip, reorder, or merge steps without explicit user approval.

[BLOCKING] Before each step or sub-skill call, update task tracking: set in_progress when step starts, set completed when step ends.

[BLOCKING] Every completed/skipped step MUST include brief evidence or explicit skip reason.

[BLOCKING] If Task tools are unavailable, create and maintain an equivalent step-by-step plan tracker with the same status transitions.

<!-- PROMPT-ENHANCE:STEP-TASK-ANCHOR:END -->

Quick Summary

Goal: Investigate and explain how existing features or logic work through READ-ONLY code exploration -- no modifications.

MANDATORY IMPORTANT MUST ATTENTION Plan ToDo Task to READ the following project-specific reference doc:

>

- project-structure-reference.md -- project patterns and structure

>

If file not found, search for: project documentation, coding standards, architecture docs.

Workflow:

1. Setup — Create analysis file, define investigation scope and metadata 2. Discovery (Phase 1A) — Glob/Grep to find all relevant files across backend and frontend 3. Deep Analysis (Phase 1B) — Read each file, build knowledge graph of relationships 4. Synthesis (Phase 2) — Map workflows, integration points, data flows, business logic 5. Report — Present findings with evidence chains and code references

Key Rules:

• READ-ONLY: never modify code, only explore and explain
• Every claim must have code evidence (no speculation or hallucination)
• Use anti-hallucination protocols: validate assumptions, chain evidence, anchor to original question
• Re-read original question every 10 operations to prevent context drift

Logical-ID Extraction & Business-Intent Rule (M3/M5)

See .claude/skills/shared/sdd-artifact-contract.md → "AI-SDD Mandates (M1-M6)" for BLOCKING criteria. When extracting operations, business rules, or events into findings:

• Assign each extracted operation/rule/event a logical ID (FR-/BR- for operations and rules) as the PRIMARY identifier. Keep the [Source: namespace/service/id] abstract-anchor evidence (never physical file:line/src/ — those live only in the provenance sidecar) as a SEPARATE carrier — never fold the source link into the rule statement itself (M3).
• For every rule, explain WHY it exists (the business intent / invariant it protects), not only WHAT the code does. State the rule in tech-agnostic business terms so the finding is reusable by a rebuild team on any stack (M5).

Skill Variant: READ-ONLY exploration - no code changes. For implementing features, use feature-implementation. For debugging, use debug-investigate.

Feature Investigation & Logic Exploration

Investigate and explain how existing features or logic work as an expert full-stack architect.

KEY PRINCIPLE: READ-ONLY investigation. Build understanding and explain how things work.

Investigation Mindset (NON-NEGOTIABLE)

Be skeptical. Apply critical thinking, sequential thinking. Every claim needs traced proof, confidence percentages (Idea should be more than 80%).

• Do NOT assume code works as named — verify by reading actual implementations
• Every finding must include file:line evidence (grep results, read confirmations)
• If you cannot prove a claim with a code trace, mark it as "inferred" with low confidence
• Question assumptions: "Does this actually do what I think?" → read the implementation, not just the signature
• Challenge completeness: "Is this all?" → grep for related usages, consumers, and cross-service references
• Verify relationships: "Does A really call B?" → trace the actual call path with evidence
• No "looks like it works" without proof — state what you verified and how

⚠️ MANDATORY: Confidence & Evidence Gate

MANDATORY IMPORTANT MUST ATTENTION declare Confidence: X% with evidence list + file:line proof for EVERY finding. 95%+ verified fact | 80-94% with caveats | 60-79% "partially verified" | <60% "inferred — needs verification", NOT fact.

IMPORTANT: Always use task tracking to plan step-by-step tasks.

---

Prerequisites

⚠️ CRITICAL: Read all protocol sections below before starting investigation.

---

Anti-Hallucination Protocols

ASSUMPTION_VALIDATION_CHECKPOINT

Before every major operation:

1. "What assumptions am I making about [X]?" 2. "Have I verified this with actual code evidence?" 3. "Could I be wrong about [specific pattern/relationship]?"

EVIDENCE_CHAIN_VALIDATION

Before claiming any relationship:

• "I believe X calls Y because..." -> show actual code
• "This follows pattern Z because..." -> cite specific examples
• "Service A owns B because..." -> grep for actual boundaries

TOOL_EFFICIENCY_PROTOCOL

• Batch multiple Grep searches into single calls with OR patterns
• Use parallel Read operations for related files
• Combine semantic searches with related keywords

CONTEXT_ANCHOR_SYSTEM

Every 10 operations:

1. Re-read the original question from the ## Metadata section 2. Verify the current operation aligns with answering the question 3. Check if we're investigating the right thing 4. Update the Current Focus bullet point within the ## Progress section

Quick Reference Checklist

Before any major operation:

• [ ] ASSUMPTION_VALIDATION_CHECKPOINT
• [ ] EVIDENCE_CHAIN_VALIDATION
• [ ] TOOL_EFFICIENCY_PROTOCOL

Every 10 operations:

• [ ] CONTEXT_ANCHOR_CHECK
• [ ] Update 'Current Focus' in ## Progress section

Emergency:

• Context Drift -> Re-read ## Metadata section
• Assumption Creep -> Halt, validate with code
• Evidence Gap -> Mark as "inferred"

---

Analysis File Structure

Create at .ai/workspace/analysis/[feature-name]-investigation.analysis.md:

## Metadata

**Original Prompt:** [Full original question/prompt]

**Task Description:** [Parsed investigation question]

**Investigation Scope:** [What needs to be understood]

**Source Code Structure:**

- Backend: services directory/{ServiceA,ServiceB,ServiceC}/
- Frontend: frontend directory/apps/, frontend directory/libs/
- Framework: framework directory/

## Progress

- **Phase**: 1A
- **Items Processed**: 0
- **Total Items**: 0
- **Current Operation**: "initialization"
- **Current Focus**: "[original task summary]"

## Errors

[Track all errors encountered during analysis]

## Assumption Validations

[Document all assumptions and their validation status]

## Performance Metrics

[Track operation times and efficiency]

## Memory Management

[Track context usage and optimization strategies]

## Processed Files

[Numbered list of processed files with status]

## File List

[Complete numbered list of all discovered files - populated during discovery]

## Knowledge Graph

[Detailed analysis of each file - populated during Phase 1B]

## Workflow Analysis

[End-to-end workflow documentation]

## Integration Points

[Cross-service and cross-component integration analysis]

## Business Logic Mapping

[Complete business logic workflows and rules]

## Data Flow Analysis

[How data flows through the system]

## Framework Pattern Usage

[Documentation of platform patterns used]

---

File Discovery Search Patterns

# Domain Entities (HIGH PRIORITY)
grep: "class.*{EntityName}.*:.*RootEntity|RootAuditedEntity"

# Commands & Queries (HIGH PRIORITY)
grep: ".*Command.*{EntityName}|{EntityName}.*Command"
grep: ".*Query.*{EntityName}|{EntityName}.*Query"

# Event Handlers (HIGH PRIORITY)
grep: ".*EventHandler.*{EntityName}|{EntityName}.*EventHandler"

# Controllers (HIGH PRIORITY)
grep: ".*Controller.*{EntityName}|{EntityName}.*Controller"

# Background Jobs (MEDIUM PRIORITY)
grep: ".*BackgroundJob.*{EntityName}|{EntityName}.*BackgroundJob"

# Message Bus Consumers (MEDIUM PRIORITY)
grep: ".*Consumer.*{EntityName}|{EntityName}.*Consumer"
grep: "MessageBusConsumer.*{EntityName}" # search for project message bus consumer base class

# Services & Helpers (LOW PRIORITY)
grep: ".*Service.*{EntityName}|{EntityName}.*Service"
grep: ".*Helper.*{EntityName}|{EntityName}.*Helper"

# Frontend Components & Stores (HIGH PRIORITY)
grep: "{feature-name}" in **/*.{ts,html}
grep: ".*Store.*{FeatureName}|{FeatureName}.*Store"
grep: ".*Component.*{FeatureName}|{FeatureName}.*Component"

File List Organization

## File List

### High Priority - Core Logic (MUST ATTENTION ANALYZE FIRST)

1. [Domain Entity path]
2. [Command/Query Handler path]
3. [Event Handler path]
4. [Controller path]
5. [Frontend Component path]
   ...

### Medium Priority - Supporting Infrastructure

10. [Background Job path]
11. [Consumer path]
12. [API Service path]
    ...

### Low Priority - Configuration/Utilities

20. [Helper path]
21. [Utility path]
    ...

**Total Files**: [count]

---

Knowledge Graph Entry Template

For each file, document:

````markdown

{ItemNumber}. {FilePath}

File Analysis:

• filePath: Full path to the file
• type: Entity | Command | Query | EventHandler | Controller | BackgroundJob | Consumer | Component | Store | Service | Helper
• architecturalPattern: CQRS | Repository | Event-Driven | Component-Store | etc.
• content: Summary of purpose and logic
• symbols: Important classes, interfaces, methods
• dependencies: All imported modules or using statements
• businessContext: What business problem, rules, contribution to feature
• referenceFiles: Other files that use this file's symbols
• relevanceScore: 1-10 for current investigation
• evidenceLevel: "verified" or "inferred"
• uncertainties: Aspects you are unsure about
• frameworkAbstractions: Framework base classes used
• serviceContext: Which microservice (ServiceB, ServiceA, ServiceC)
• dependencyInjection: DI registrations
• genericTypeParameters: Generic type relationships

Message Bus Analysis (FOR CONSUMERS ONLY):

• messageBusMessage: Message type consumed
• messageBusProducers: Files that publish this message (MUST ATTENTION grep across ALL services)
• crossServiceIntegration: Cross-service data flow description

Targeted Aspect Analysis:

For Frontend Components:

• componentHierarchy, routeConfig, routeGuards, stateManagementStores
• dataBindingPatterns, validationStrategies, apiIntegration, userInteractionFlow

For Backend Components:

• authorizationPolicies, commands, queries, domainEntities
• repositoryPatterns, businessRuleImplementations, eventHandlers, backgroundJobs

For Consumer Components:

• messageBusMessage, messageBusProducers, crossServiceIntegration
• handleLogicWorkflow, dependencyWaiting

Code Examples:

// Include relevant code snippets that demonstrate key logic

Key Insights:

[Important observations about this file's role in the overall feature] ````

---

Overall Analysis Template

````markdown

Overall Analysis

1. Complete End-to-End Workflows Discovered

Workflow: {Feature Name} - Main Flow

[User Action] -> [Frontend Component] -> [API Service] -> [Controller]
|
[Command/Query Handler]
|
[Domain Entity] -> [Repository]
|
[Event Handler] -> [Side Effects]

Detailed Flow:

1. Frontend Entry Point: Component.ts:line - User interaction, validation, API call 2. API Layer: Controller.cs:line - Endpoint, authorization, command dispatch 3. Application Layer: CommandHandler.cs:line - Validation, business logic, repository ops 4. Domain Layer: Entity.cs:line - Business rules, state changes, domain events 5. Event Handling: EventHandler.cs:line - Events handled, side effects, integrations 6. Cross-Service: Consumer.cs:line - Message consumed, producer service, sync logic

2. Key Architectural Patterns and Relationships

• CQRS: Commands, queries, separation of concerns
• Event-Driven: Domain events, handlers, message bus
• Repository: Repositories used, query builders, extensions
• Frontend: Component hierarchy, state management, forms

3. Business Logic Workflows

Frontend-to-backend flow tree and cross-service integration flow.

4. Integration Points and Dependencies

API endpoints, message bus integration, database dependencies, external services.

5. Business Rules Discovered

Validation rules, business constraints, authorization rules.

6. Framework Pattern Usage

Backend: CQRS, repository, event handlers, message bus, background jobs, validation Frontend: Component hierarchy, stores, forms, API services, reactive patterns

7. Key Insights and Observations

Critical findings, recommendations, uncertainties requiring clarification. ````

---

Presentation Template

## Answer

[Direct answer to the question in 1-2 paragraphs]

## How It Works

### 1. [First Step]

[Explanation with code reference at `file:line`]

### 2. [Second Step]

[Explanation with code reference at `file:line`]

## Key Files

| File                  | Purpose   |
| --------------------- | --------- |
| `path/to/file.cs:123` | [Purpose] |

## Data Flow

[Text diagram showing the flow]

## Want to Know More?

I can explain further:

- [Topic 1]
- [Topic 2]
- [Topic 3]

---

Common Investigation Scenarios

"How does feature X work?"

1. Find entry points (API, UI, job) 2. Trace through command/query handlers 3. Document entity changes 4. Map side effects (events, notifications)

"Where is the logic for Y?"

1. Search for keywords in commands, queries, entities 2. Check event handlers for side effect logic 3. Look in helper/service classes 4. Check frontend stores and components

"What happens when Z occurs?"

1. Identify the trigger (user action, event, schedule) 2. Trace the handler chain 3. Document all side effects 4. Map error handling

"Why does A behave like B?"

1. Find the relevant code path 2. Identify decision points 3. Check configuration/feature flags 4. Document business rules

---

Project-Specific Investigation Patterns

Backend Patterns to Look For (see docs/project-reference/backend-patterns-reference.md)

• CQRS command / query base classes - CQRS entry points
• Entity event application handler - Side effects
• Message bus consumer base class - Cross-service consumers
• Service-specific repository interfaces - Data access
• Project validation fluent API - Validation logic
• Project authorization attributes - Authorization

Frontend Patterns to Look For (see docs/project-reference/frontend-patterns-reference.md)

• Project store component base (search for: store component base class) - State management components
• Project store base (search for: store base class) - Store implementations
• effectSimple / tapResponse - Effect handling
• observerLoadingErrorState - Loading/error states
• API services extending project API service base class

---

Investigation Flow

Phase 1A: Initialize & Discover

1. Create analysis file at .ai/workspace/analysis/[feature-name]-investigation.analysis.md

• Use the Analysis File Structure template above

2. Search for all related files using grep patterns organized by priority

• Use the File Discovery Search Patterns above

3. Save all discovered paths as numbered list under ## File List, organized by priority 4. Update Total Items count in ## Progress

Phase 1B: Knowledge Graph Construction

1. Count total files, split into batches of 10 (priority order) 2. Insert batch analysis tasks into todo list 3. For each file, document in ## Knowledge Graph

• Use the Knowledge Graph Entry Template above

4. Every 10 files: Update progress, run CONTEXT_ANCHOR_CHECK

Phase 1C: Overall Analysis

After ALL files analyzed, write comprehensive analysis:

• End-to-end workflows, architectural patterns, business logic
• Integration points, business rules, platform patterns, key insights
• Use the Overall Analysis Template above

Phase 2: Presentation

Present findings in clear format with: Answer, How It Works (with code refs), Key Files table, Data Flow diagram, "Want to Know More?" topics.

• Use the Presentation Template above

---

Anti-Hallucination Protocols (Investigation-Specific)

Prerequisites:

---

Investigation Guidelines

• Evidence-based: Every claim must have code evidence
• Service boundary awareness: Understand which service owns what
• Framework pattern recognition: Identify project framework patterns used
• Cross-service tracing: Follow message bus flows across services
• Read-only exploration: Never suggest changes unless asked
• Question-focused: Always tie findings back to the original question
• Layered explanation: Start simple, offer deeper detail if requested

---

Graph Intelligence

RECOMMENDED if .code-graph/graph.db exists.

Graph-Trace for Feature Flow

When graph DB is available, use trace to understand the complete feature flow:

• python .claude/scripts/code_graph trace <entry-file> --direction both --json — full upstream (who triggers) + downstream (what it affects) flow
• Use --direction downstream when investigating "what happens after X"
• Use --direction upstream when investigating "what triggers X"
• Trace reveals implicit connections (MESSAGE_BUS, events) that grep misses

See Also

• feature-implementation - For implementing new features (code changes)
• debug-investigate - For debugging and fixing issues
• planning - For creating implementation plans
• graph-query - Natural language graph queries for code relationships

References

Note: All content from references/investigation-protocols.md has been merged into this skill file above. The reference file is kept for historical purposes.

---

Workflow Recommendation

MANDATORY IMPORTANT MUST ATTENTION — NO EXCEPTIONS: If you are NOT already in a workflow, you MUST ATTENTION use a direct user question 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:

>

1. Activate `investigation` workflow (Recommended) — scout → investigate

2. Execute `$investigate` directly — run this skill standalone

---

Next Steps

MANDATORY IMPORTANT MUST ATTENTION — NO EXCEPTIONS after completing this skill, you MUST ATTENTION use a direct user question to present these options. Do NOT skip because the task seems "simple" or "obvious" — the user decides:

• "$plan (Recommended)" — Create implementation plan from investigation findings
• "$domain-analysis" — If investigation reveals entity-heavy feature (new aggregates, complex invariants), model domain before planning
• "$fix" — If investigating a bug to fix
• "Skip, continue manually" — user decides

[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) (read directly when relevant; do not rely on hook-injected conversation text)

Evidence Gate: MANDATORY IMPORTANT MUST ATTENTION — every claim, finding, and recommendation requires file:line proof or traced evidence with confidence percentage (>80% to act, <80% must verify first).

External Memory: For complex or lengthy work (research, analysis, scan, review), write intermediate findings and final results to a report file in plans/reports/ — prevents context loss and serves as deliverable.

<!-- SYNC:understand-code-first -->

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. — why: long context drifts from the file; the file is ground truth

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

>

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

<!-- /SYNC:understand-code-first -->

<!-- SYNC:evidence-based-reasoning -->

Evidence-Based Reasoning — Speculation is FORBIDDEN. Every claim needs proof.

>

1. Cite file:line, grep results, or framework docs for EVERY claim

2. Declare confidence: >80% act freely, 60-80% verify first, <60% DO NOT recommend

3. Cross-service validation required for architectural changes

4. "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: [...]."

<!-- /SYNC:evidence-based-reasoning -->

<!-- SYNC:incremental-persistence -->

Incremental Result Persistence — MANDATORY for all sub-agents or heavy inline steps processing >3 files.

>

1. Before starting: Create report file plans/reports/{skill}-{date}-{slug}.md

2. After each file/section reviewed: Append findings to report immediately — never hold in memory

3. Return to main agent: Summary only (per SYNC:subagent-return-contract) with Full report: path

4. Main agent: Reads report file only when resolving specific blockers

>

Why: Context cutoff mid-execution loses ALL in-memory findings. Each disk write survives compaction. Partial results are better than no results.

>

Report naming: plans/reports/{skill-name}-{YYMMDD}-{HHmm}-{slug}.md

<!-- /SYNC:incremental-persistence -->

<!-- SYNC:subagent-return-contract -->

Sub-Agent Return Contract — When this skill spawns a sub-agent, the sub-agent MUST return ONLY this structure. Main agent reads only this summary — NEVER requests full sub-agent output inline.

>

```markdown

## Sub-Agent Result: [skill-name]

>

Status: ✅ PASS | ⚠️ PARTIAL | ❌ FAIL

Confidence: [0-100]%

>

### Findings (Critical/High only — max 10 bullets)

>

- [severity] [file:line] [finding]

>

### Actions Taken

>

- [file changed] [what changed]

>

### Blockers (if any)

>

- [blocker description]

>

Full report: plans/reports/[skill-name]-[date]-[slug].md

```

>

Main agent reads Full report file ONLY when: (a) resolving a specific blocker, or (b) building a fix plan.

Sub-agent writes full report incrementally (per SYNC:incremental-persistence) — not held in memory.

<!-- /SYNC:subagent-return-contract -->

<!-- SYNC:nested-task-creation -->

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.

<!-- /SYNC:nested-task-creation -->

<!-- SYNC:project-reference-docs-guide -->

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.

<!-- /SYNC:project-reference-docs-guide -->

<!-- SYNC:task-tracking-external-report -->

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.

<!-- /SYNC:task-tracking-external-report -->

<!-- SYNC:critical-thinking-mindset -->

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.

<!-- /SYNC:critical-thinking-mindset -->

<!-- SYNC:sequential-thinking-protocol -->

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

<!-- /SYNC:sequential-thinking-protocol -->

<!-- SYNC:cross-service-check -->

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

<!-- /SYNC:cross-service-check -->

<!-- SYNC:source-test-drift-check -->

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.

<!-- /SYNC:source-test-drift-check -->

<!-- SYNC:ai-mistake-prevention -->

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.

<!-- /SYNC:ai-mistake-prevention -->

<!-- SYNC:understand-code-first:reminder -->

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

<!-- SYNC:critical-thinking-mindset:reminder -->

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

<!-- /SYNC:critical-thinking-mindset:reminder -->

<!-- SYNC:sequential-thinking-protocol:reminder -->

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

<!-- /SYNC:sequential-thinking-protocol:reminder -->

<!-- SYNC:ai-mistake-prevention:reminder -->

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

<!-- /SYNC:ai-mistake-prevention:reminder -->

<!-- SYNC:task-tracking-external-report:reminder -->

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

<!-- /SYNC:task-tracking-external-report:reminder -->

<!-- SYNC:project-reference-docs-guide:reminder -->

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

<!-- /SYNC:project-reference-docs-guide:reminder -->

<!-- SYNC:nested-task-creation:reminder -->

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

<!-- /SYNC:nested-task-creation:reminder -->

<!-- PROMPT-ENHANCE:STEP-TASK-CLOSING:START -->

Prompt-Enhance Closing Anchors

IMPORTANT MUST ATTENTION follow declared step order for this skill; NEVER skip, reorder, or merge steps without explicit user approval IMPORTANT MUST ATTENTION for every step/sub-skill call: set in_progress before execution, set completed after execution IMPORTANT MUST ATTENTION every skipped step MUST include explicit reason; every completed step MUST include concise evidence IMPORTANT MUST ATTENTION if Task tools unavailable, maintain an equivalent step-by-step plan tracker with synchronized statuses

<!-- PROMPT-ENHANCE:STEP-TASK-CLOSING:END -->

Closing Reminders

MANDATORY IMPORTANT MUST ATTENTION break work into small todo tasks using task tracking BEFORE starting. MANDATORY IMPORTANT MUST ATTENTION validate decisions with user via a direct user question — never auto-decide. MANDATORY 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.

[IMPORTANT] Analyze how big the task is and break it into many small todo tasks systematically before starting — this is very important.

<!-- CODEX:SYNC-PROMPT-PROTOCOLS:START -->

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.

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. Any supported AI tool may execute when this shared context and local docs are available.

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 unless the user explicitly invoked a workflow/skill and the local protocol treats explicit invocation as confirmation:

• 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. Goal-driven execution: Define success criteria first, loop until verified, and stop only when observable checks pass. Tests verify intent: Tests must protect business rules/invariants and fail when the protected intent breaks, not only mirror current behavior.

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

<!-- CODEX:SYNC-PROMPT-PROTOCOLS:END -->