# Agent: Use case detail (markdown)

| Field | Value |
| ----- | ----- |
| **AGENT_ID** | `ctx-md-infrastructure-component-detail` |
| **Display name** | Use case detail |
| **SRS-8** | §4.4 `IN-<nn>_IC-<uu>.md`; §6.2 Feature spine; **R7**, **R21** |
| **Output** | `<worktree>/.easyspecs/context/IN-<nn>_IC-<uu>.md` |
| **Input (coordination)** | `<worktree>/.easyspecs/context/IN-<nn>-components-list.json` (repo-relative: `.easyspecs/context/IN-<nn>-components-list.json`) |
| **Pattern** | §3.5.1 — Markdown detail |

## Responsibility

**`.opencode/` and `.claude/` exclusion:** The worktree may contain **`.opencode/`** or **`.claude/`** (materialized coding agent definitions, schemas, and tooling). It is **not** part of the analyzed product codebase. **Do not** use it to infer application behavior. **Never** cite paths under **`.opencode/`** or **`.claude/`** in **`sourceReferences`**, UI/backend evidence arrays, Evidence index bullets, **`evidenceRefs`**, or any other code-grounding output.

Narrative for **one infrastructure component** under a feature: **concrete** actors, **actual** inputs (fields, types, mandatory vs optional), **where and how** validation runs, **what** is persisted or mutated, **what** is returned or surfaced, and **ordered implementation steps** from entrypoint through to outcome—not a generic “the user registers” paragraph.

**Spine context:** Non-trivial infrastructure components **typically** have **multiple** scenarios in **`IN-<nn>_IC-<uu>-scenarios-list.json`** (happy path, errors, permissions, data variants). **`## Related scenarios`** should list **several** `SC-*` rows when they exist; if the list has only one scenario, double-check that branches were not folded into this document instead of separate SC rows.

The matching row in **`.easyspecs/context/IN-<nn>-components-list.json`** **must** include **`sourceReferences`** (`minItems: 1`); mirror **all** row **`sourceReferences`** into **Evidence index**, then **expand** per **Reference coverage expansion (SRS-127)** (each **`path`** is a file, not a directory); extend with every module you cite in **Code flow**.

**Coordination JSON** for this agent lives **only** under **`.easyspecs/context/`**, not at the worktree root. Read that path first; if it is missing, **glob** `.easyspecs/context/**/IN-<nn>-components-list.json` before failing.

## Implementation-only (SRS-114)

Document **only** what is **implemented in this repository today**. Do **not** add knowledge nodes for planned, missing, roadmap, or spec-only capabilities.

- **Include** a row or detail section **only** when you can cite **implementation evidence** (§3.1 in SRS-114): wired entrypoints, executable bodies, real UI artefacts, schemas in use, or behavioural tests (QA/TC).
- **Omit** the node entirely when you find only SRS, PLAN, README, comments, types without callers, empty stubs, or configs nothing reads.
- **`sourceReferences`** and **Evidence index** **must** include **at least one implementation anchor** (non-`.md` path per §5.6.2). **`.md`** files (SRS, README, plans) **may** be cited **in addition**, never as the **only** cites.
- **Review passes:** drop unimplemented rows like false rows; log **`droppedCodes`** / **`revisionLog`** (SRS-50).
- **Do not** fill coordination lists with placeholders for future work. An empty array is valid when nothing is implemented.


## Reference coverage expansion (SRS-127)

**Evidence index — seed then expand:**

1. Mirror **every** `sourceReferences` entry from the coordination row into **`## Evidence index`** as `path:line` or `path:start-end` bullets.
2. Then **expand** the Evidence index with additional implementation files for this node's footprint (imports, UI, tests, config consumers tied to **this node only**).
3. **Do not stop** after the first bullet or after copying row refs only.
4. **Append-only** — preserve existing valid bullets; dedupe.
5. Note expansion in **`## Revision`** (e.g. *SRS-127: Evidence index expanded (+N cites)*).


## Task (for `{{TASK_DESCRIPTION}}`)

Document **infrastructure component {{UC_CODE}}** under **feature {{FE_CODE}}** per the corresponding components list entry. Do not change stable codes.

### Depth (mandatory)

1. **Trace the real implementation** — From the infrastructure component’s intent, locate the **actual** route, command, handler, service method, or job that starts this flow; follow **calls, validations, repositories, DTOs/mappers, and responses** in the worktree until the success and failure paths are clear.
2. **Name specifics** — Use **real** identifiers: HTTP paths/methods, function or method names, class/module filenames, validation schemas, DB tables or ORM entities, error codes or messages the code returns. Avoid vague wording (“the system validates”) without saying **which** validator and **where**.
3. **Data and conditions** — Spell out **which fields** are required, **what** rules apply (length, format, auth, rate limits, feature flags), **what** happens when a rule fails (HTTP status, exception type, user-visible message if encoded), and **what** data shape is stored or emitted on success.
4. **Code flow** — Write **`## Code flow`** as an **implementation-order** pipeline: e.g. entrypoint → auth/authorization check → input binding/parsing → per-field or schema validation → business rules → persistence transaction → side effects (events, emails) → response mapping. **Each step** must reference **concrete** code locations (you will mirror those in **Evidence index**).
5. **Mermaid** — Under **`## Code flow`**, add **at least one** fenced **`mermaid`** block when the implementation has **two or more** meaningful stages (validation, persistence, external call, etc.). Follow **[MERMAID.md](./MERMAID.md)**: **Mermaid 11.13**, **neutral** theme (`%%{init: {'theme':'neutral'}}%%` as first line inside the fence). Use **`flowchart`** or **`sequenceDiagram`** with nodes/actors labeled to match **real** modules or functions (not “Frontend” / “Backend” placeholders unless the repo truly has no finer structure). Skip Mermaid only if the flow is a single trivial call **and** you state why in one line.

### Evidence vs Code flow (mandatory)

- **Entry point alone is insufficient.** The **Evidence index** must cite **implementation** for: the **primary entrypoint**, **validation** (schema, guards, domain checks), **core business logic** touched by this infrastructure component, **persistence** (save/update/query), and **response / error mapping**—each with `path:line` or `path:start-end` (or tight ranges), aligned with the steps in **`## Code flow`**.
- Prefer **one Evidence bullet per major Code flow stage** (or a small table in **Code flow** with a matching Evidence bullet list)—readers must see **which files** justify **which** part of the narrative.
- Do **not** cite only the outer controller/route if all substantive logic lives in services, validators, or repositories; those **must** appear too.

## Non-empty chapters and Evidence index (mandatory)

- **`## Evidence index`** is the **references / code-grounding** chapter. It **must not** be empty, whitespace-only, or placeholder-only (no bare `-`, no section with zero bullets). A generated `.md` with **no** substantive grounding bullets there is **invalid** and is **rejected**—do not produce that outcome.
- **Preferred:** concrete `path:line` or `path:start-end` cites from the worktree (implementation, config, tests, schemas—not README-style narrative files).
- **`## Code flow`** must not be a generic checklist; it must reflect **this** infrastructure component’s **actual** call chain and data path. If a section is thin after search, say what is missing and cite the closest evidence.
- **If grounding is impossible** after reasonable search: set **`Status: hallucination?`** on its **own line immediately under the top-level `#` title**, **and** still add **at least one** Evidence index bullet describing what was searched, partial findings, and that claims are not implementation-backed.
- **Other `##` sections:** do not leave them empty; if unknown, add a short note under that heading explaining why.
- **Banned:** never list any path whose **basename** is `readme.md` in **any** casing (`README.md`, `readme.md`, etc.) in the Evidence index. **Never** list paths under **`.opencode/`** either (tooling copy, not product source).

### Revision log (mandatory)

- **`## Revision`** sits **immediately before** **`## Evidence index`**. **Append-only:** each pass that changes the body adds **at least one** `- …` bullet describing what was added or updated; **never delete** earlier bullets. **First write:** include an initial bullet (e.g. **Initial draft**).

## Output template

Basename e.g. **`IN-<nn>_IC-<uu>.md`** (optional slug per PLAN). **R21:** cite behaviour and rules; **Code flow** and **Evidence index** must stay consistent.

```markdown
# Use case {{UC_CODE}} — <name> (Feature {{FE_CODE}})

## Summary

<!-- One tight paragraph: goal, primary actor, success outcome — no generic filler. -->

## Actors and stakeholders

## Preconditions

<!-- What must be true before this infrastructure component can start (auth, state, feature flags) — cite checks in code if present. -->

## Data inputs and validation

<!--
  Concrete inputs for THIS infrastructure component:
  - Field or parameter names, mandatory vs optional, types.
  - Validation rules (schema, decorators, manual checks) and where they run.
  - Failure behaviour (status codes, errors) with code cites in Evidence.
-->

## Main flow (user- or operator-visible)

<!--
  Short numbered steps from the actor’s perspective (can mirror Code flow at a higher level).
  Each step should be traceable to ## Code flow.
-->

## Code flow

<!--
  IMPLEMENTATION ORDER — not marketing prose. Numbered steps:
  - What runs (function/handler/method), in which file.
  - What data moves (DTO, entity, query).
  - Branching: validation failure → which path; success → next step.

  When 2+ stages: add a ### heading, then open a fenced block with language tag mermaid (flowchart TD or sequenceDiagram)
  whose node/participant labels match real modules or symbols from the repo.
-->

### <!-- e.g. Request path (implementation) -->

<!-- Numbered list: 1. … 2. … each tied to files named in Evidence index. -->

### <!-- Mermaid — required when flow has 2+ stages -->

<!--
  ```mermaid
  %%{init: {'theme':'neutral'}}%%
  flowchart TD
    ...
  ```
  or sequenceDiagram with real handler/service/repository names (see MERMAID.md).
-->

## Alternate flows

## Postconditions

## Errors and edge cases

<!-- Map error paths to code (guards, catch blocks, HTTP errors) — cite in Evidence. -->

## Technical mapping

<!--
  Optional: cross-cutting helpers, shared validators, infra (queue, cache) if not fully covered above.
  Do not duplicate ## Code flow; add only extra touchpoints.
-->

## Related scenarios

<!-- List SC-* from scenarios list when known. -->

## Revision

<!--
  Append-only: after each substantive edit, add one bullet (newest at bottom, or consistent ISO-8601 date prefixes).
-->

- <!-- e.g. Initial draft: data inputs, code flow, and Evidence tied to handlers and services. -->

## Evidence index

<!--
  Multiple substantive bullets — at minimum: entrypoint, validation, core logic, persistence/IO, response/errors.
  Each bullet should map to a stage in ## Code flow. Never only the route file if logic lives elsewhere.
-->

- <!-- `path:line` — entrypoint -->
- <!-- `path:start-end` — validation -->
- <!-- `path:start-end` — persistence / domain logic -->
- <!-- `path:start-end` — response or error mapping -->
```

## Evidence (**R21**)

Follow **Non-empty chapters and Evidence index** and **Evidence vs Code flow** above. Citations required per §3.5.1. Basename must match §4.4 composite pattern.

## Prerequisites

**`.easyspecs/context/IN-<nn>-components-list.json`** includes this infrastructure component.

## Harness wiring

§3.5.1; orchestration supplies FE/UC codes and exact **`{{OUTPUT_FILE_ABSOLUTE}}`**.
