[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 ATTENTION ask user whether to skip.

1. Detect & Gather — Auto-detect modules from git changes OR user-specified module, read existing docs
2. Investigate Code — Grep/glob codebase to gather evidence (

   file:line

   format) for every test case
3. Write Documentation — Follow exact 26-section structure, place in

   docs/business-features/{Module}/

4. Generate AI Companion — Create

   .ai.md

   file (max 300 lines) with domain model, file locations, key expressions
5. Verification — 3-pass system: evidence audit, domain model verification, cross-reference audit

• EVERY test case MUST ATTENTION have verifiable code evidence (

  FilePath:LineNumber

  ), no exceptions
• Output must have exactly 26 sections matching the master template
• Always update CHANGELOG.md and Version History (Section 26) when modifying docs
• When writing Section 17 test cases: include an

  IntegrationTest

  field pointing to the test file and method name. Format:

  IntegrationTest: Orders/OrderCommandIntegrationTests.cs::{MethodName}

  . If no integration test exists yet, set

  Status: Untested

  .
• Verify every TC-{MOD}-XXX in Section 17 has a corresponding

  [Trait("TestSpec", "TC-{MOD}-XXX")]

  in the integration test codebase. If missing, flag as

  Status: Untested

  .
• If third verification pass finds >5 issues, HALT and re-run verification

• docs/project-reference/domain-entities-reference.md

  — Domain entity catalog, relationships, cross-service sync (read when task involves business entities/models) (content auto-injected by hook — check for [Injected: ...] header before reading)

• Search for:

  business-features

  ,

  detailed-features

  ,

  feature-docs-template

• Look for: existing feature doc folders, 26-section templates, AI companion files

MANDATORY IMPORTANT MUST ATTENTION Read the

feature-docs-reference.md

companion doc for project-specific patterns and code examples. If file not found, continue with search-based discovery above.

1. Run

   git diff --name-only HEAD

   (captures both staged and unstaged changes)
2. If no uncommitted changes, run

   git diff --name-only HEAD~1

   (last commit)
3. Extract unique module names from changed file paths using the Module Mapping table
4. For each detected module, check if a business feature doc exists in

   docs/business-features/{Module}/

5. If docs exist → proceed to Phase 1.5 (Update Mode) for each module
6. If no docs exist → skip (do not create docs from scratch without explicit user request)
7. If no service-layer files changed (e.g., only

   .claude/

   ,

   docs/

   , config files) → report "No business feature docs impacted" and exit

src/Services/{Module}/**

{frontend-apps-dir}/{app-name}/**

{frontend-libs-dir}/{domain-lib}/src/{feature}/**

ls -d src/Services/*/
ls -d {frontend-apps-dir}/*/

1. User explicitly specifies module name
2. Feature name/domain implies module (search codebase to verify mapping)
3. Search codebase for feature-related entities/commands
4. Auto-detected from git diff (Step 1.0 above) — used when invoked as a workflow step without explicit module

1. Read

   docs/BUSINESS-FEATURES.md

   (master index)
2. Read

   docs/business-features/{Module}/INDEX.md

   (if exists)
3. Read

   docs/business-features/{Module}/README.md

   (if exists)
4. Identify what already exists vs what needs creation/update

• Entities:

  src/Services/{Module}/{Module}.Domain/Entities/

• Commands:

  src/Services/{Module}/{Module}.Application/UseCaseCommands/

• Queries:

  src/Services/{Module}/{Module}.Application/UseCaseQueries/

• Controllers:

  src/Services/{Module}/{Module}.Service/Controllers/

• Frontend:

  {frontend-apps-dir}/{app-name}/

  or

  {frontend-libs-dir}/{domain-lib}/

1. Domain Entity Discovery: Entities, value objects, enums
2. Workflow Discovery: Commands, Queries, Event Handlers, Background Jobs
3. API Discovery: Controllers, endpoints, DTOs
4. Frontend Discovery: Components, Services, Stores
5. Cross-Service Discovery: Message Bus messages, producers, consumers

1. Identify the source of changes (git diff, branch comparison, commit history)
2. Categorize changes by type: backend entity, command, query, frontend component, i18n, etc.
3. Map each change to impacted documentation sections (use table below)

• Section 17 (Test Specifications): Add test cases (TC-{MOD}-XXX) for new features with GIVEN/WHEN/THEN format. Each TC entry should include:
  markdown

  #### TC-GM-001: Create SMART Goal Successfully
  
  **Priority**: P0-Critical
  **Status**: Tested | Untested
  **IntegrationTest**: `Orders/OrderCommandIntegrationTests.cs::SaveOrder_WhenValidData_ShouldCreateSuccessfully`
  **Evidence**: `{Service}.Application/{Feature}/Commands/Save{Feature}Command.cs:42-68`

• Section 18 (Test Data): Add seed data required for new test cases
• Section 19 (Edge Cases): Add edge cases for boundary conditions, error states, permission checks
• Section 20 (Regression Impact): Add regression risk rows for impacted areas, update test suite counts

• AC-01: {Criterion with evidence reference}
• AC-02: {Criterion with evidence reference}

{FilePath}:{LineRange}

**Test Summary Table (MANDATORY)**:

```markdown
| Category    | P0 (Critical) | P1 (High) | P2 (Medium) | P3 (Low) |  Total  |
| ----------- | :-----------: | :-------: | :---------: | :------: | :-----: |
| {Category1} |      {N}      |    {N}    |     {N}     |   {N}    |   {N}   |
| **Total**   |    **{N}**    |  **{N}**  |   **{N}**   | **{N}**  | **{N}** |

undefined

• {Passing criteria 1}
• {Passing criteria 2}

• {Invalid scenario} → {Expected error/behavior}

{FilePath}:{LineRange}

**Troubleshooting Format**:

```markdown

1. {Cause 1}
2. {Cause 2}

• {Step 1}
• {Step 2}

**Permission Matrix**:

```markdown
| Role  | View | Create | Edit | Delete | Special     |
| ----- | :--: | :----: | :--: | :----: | ----------- |
| Admin |  ✅  |   ✅   |  ✅  |   ✅   | Full access |

1. Tables over prose - Convert paragraphs to table rows
2. Paths over descriptions -

   File:Line

   over "located in..."
3. Signatures over examples -

   { id: string } → { entity: Dto }

   over full code
4. Decisions over explanations - What to do, not why

1. Quick Reference (~40 lines) - Module, service, file locations
2. Domain Model (~80 lines) - Entities, enums, value objects (condensed)
3. API Contracts (~100 lines) - Signatures with DTOs only
4. Validation Rules (~80 lines) - BR-XX table format
5. Service Boundaries (~60 lines) - Cross-service integration
6. Critical Paths (~60 lines) - Key workflows as decision trees

AI-optimized context file for code generation tasks. Full documentation: README.{FeatureName}Feature.md Last synced: {YYYY-MM-DD}

undefined

• Troubleshooting (operational)
• Operational Runbook (DevOps)
• Business Value (stakeholder)
• Version History (changelog)
• Glossary (definitions)

• File size ≤300 lines (standard) or ≤500 lines (extended)
• All file paths are exact and current
• API contracts include request/response shapes
• Business rules have evidence references
• Patterns section has required/anti-pattern markers
• Evidence chain preserved from full doc
• Links back to comprehensive doc
• 'Last synced' timestamp included

docs/BUSINESS-FEATURES.md

1. Read current content
2. Verify module is listed in the "Detailed Module Documentation" table
3. Add link if missing:
   markdown

   | **{Module}** | [Description] | [View Details](./business-features/{Module}/README.md) |

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

• "Have I read the actual code that implements this?"
• "Are my line number references accurate and current?"
• "Can I provide a code snippet as evidence?"

1. Read the Evidence file at claimed line number
2. Verify: Does code at that line support test assertion?
3. Check Edge Cases: Find error constants in

   ErrorMessage.cs

4. Fix immediately if line numbers wrong

1. Read the Evidence file at the claimed line number
2. Verify match: Does the code at that line support the test assertion?
3. Check Edge Cases: Find error message constants in

   ErrorMessage.cs

4. Fix immediately if line numbers are wrong

• Read EACH entity file referenced in Domain Model section
• Verify property names, types, and line numbers
• Check enum values exist in actual source
• Remove any documented properties not found in source

• Test Summary counts match actual test case count
• All internal links work
• No template placeholders remain (

  {FilePath}

  ,

  {LineRange}

  )
• ErrorMessage.cs constants match edge case messages

• Documentation placed in correct folder structure
• README.md follows template format (26 sections)
• INDEX.md created with navigation links
• Master index (BUSINESS-FEATURES.md) updated
• Stakeholder navigation table present
• ASCII diagrams for architecture
• API endpoints documented with examples
• CHANGELOG.md updated with entry under

  [Unreleased]

• EVERY test case has Evidence field with

  file:line

  format
• No template placeholders remain (

  {FilePath}

  ,

  {LineRange}

  )
• Line numbers verified by reading actual source files
• Edge case errors match constants from

  ErrorMessage.cs

• Test Summary counts match actual number of test cases

• All entity properties verified against source code
• All enum values verified against actual enum definitions
• No invented methods, properties, or models
• All code snippets copied from actual files

• documentation

• feature-implementation

• IMPORTANT MUST ATTENTION break work into small todo tasks using

  TaskCreate

  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: <!-- SYNC:evidence-based-reasoning:reminder -->
• IMPORTANT MUST ATTENTION cite

  file:line

  evidence for every claim. Confidence >80% to act, <60% = do NOT recommend. <!-- /SYNC:evidence-based-reasoning:reminder -->