[IMPORTANT] Use TaskCreate 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 ask user whether to skip.

Prerequisites: MUST READ before executing:

Scan & Update Reference Doc — Read existing doc first, scan codebase for current state, diff against doc content, update only changed sections, preserve manual annotations. MUST READ .claude/skills/shared/scan-and-update-reference-doc-protocol.md for full protocol and checklists.

Quick Summary

Goal: Scan backend codebase and populate docs/project-reference/backend-patterns-reference.md with actual repository patterns, CQRS command/query structures, validation patterns, entity conventions, event handlers, and migration approaches. (content auto-injected by hook — check for [Injected: ...] header before reading)

Workflow:

1. Read — Load current target doc, detect init vs sync mode
2. Scan — Discover backend patterns via parallel sub-agents
3. Report — Write findings to external report file
4. Generate — Build/update reference doc from report
5. Verify — Validate code examples reference real files

Key Rules:

• Generic — works with any backend framework (.NET, Node.js, Java, etc.)
• Detect framework first, then scan for framework-specific patterns
• Every code example must come from actual project files with file:line references

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

Scan Backend Patterns

Phase 0: Read & Assess

1. Read docs/project-reference/backend-patterns-reference.md
2. Detect mode: init (placeholder) or sync (populated)
3. If sync: extract existing sections and note what's already well-documented

Phase 1: Plan Scan Strategy

Detect backend framework:

• .csproj files → .NET (check for MediatR, CQRS patterns)
• package.json with express/fastify/nestjs → Node.js
• pom.xml / build.gradle → Java/Kotlin
• requirements.txt / pyproject.toml → Python

Use docs/project-config.json contextGroups/modules if available for service paths.

Phase 2: Execute Scan (Parallel Sub-Agents)

Launch 3 Explore agents in parallel:

Agent 1: Repository & Entity Patterns

• Grep for repository interfaces (interface I*Repository, extends Repository)
• Find entity/model classes (base class inheritance, attributes/annotations)
• Find DTO classes and mapping patterns (AutoMapper, manual mapping, MapTo* methods)
• Discover data access patterns (Unit of Work, DbContext, MongoDB collections)
• Look for extension methods on repositories

Agent 2: CQRS & Command/Query Patterns

• Grep for command handlers (IRequestHandler, CommandHandler, @CommandHandler)
• Grep for query handlers, query objects
• Find validation patterns (FluentValidation, class-level validators, middleware)
• Discover request/response wrapper patterns (Result<T>, ApiResponse)
• Find authorization attributes/decorators on handlers

Agent 3: Events, Migrations & Infrastructure

• Grep for event handlers, domain events, integration events
• Find message bus consumers/publishers (MassTransit, RabbitMQ, Kafka patterns)
• Discover migration patterns (EF migrations, Flyway, custom migrators)
• Find background job patterns (Hangfire, Quartz, hosted services)
• Grep for middleware, filters, interceptors

Write all findings to: plans/reports/scan-backend-patterns-{YYMMDD}-{HHMM}-report.md

Phase 3: Analyze & Generate

Read the report. Build these sections:

Target Sections

Content Rules

• Show actual code snippets (5-15 lines) from the project with file:line references
• Include "DO" and "DON'T" examples where anti-patterns are clear
• Use tables for convention summaries (naming, file locations, base classes)
• Group patterns by concern, not by framework feature

Phase 4: Write & Verify

1. Write updated doc with <!-- Last scanned: YYYY-MM-DD --> at top
2. Verify: 5 code example file paths exist (Glob check)
3. Verify: class names in examples match actual class definitions
4. Report: sections updated, patterns discovered, coverage gaps

Closing Reminders

• MUST break work into small todo tasks using TaskCreate BEFORE starting
• MUST search codebase for 3+ similar patterns before creating new code
• MUST cite file:line evidence for every claim (confidence >80% to act)
• MUST add a final review todo task to verify work quality MANDATORY IMPORTANT MUST READ the following files before starting:
• MUST READ .claude/skills/shared/scan-and-update-reference-doc-protocol.md before starting