Intent

Keep code comments structural and stable, and put narrative framing (the "story") in docs that can evolve without forcing code rewrites.

This skill is useful when a request says:

"Tell the story" / "make it interview-ready"
"Explain the flow end-to-end"
"Write the narrative / walkthrough"

Rules

Code comments must stay structural

When editing code, prefer stable, non-story comments:

Where this fits (call chain, module boundaries)
Inputs/outputs
Guardrails and failure modes
Determinism/provenance notes (seed, metadata, reproducibility)

Avoid story framing inside code (examples of what NOT to bake into code comments):

Persona narratives ("as a port manager...")
Consulting case framing ("client asks us to...")
Overly specific interview scripts

Narrative framing belongs in docs

When asked to "tell the story", create/maintain these docs:

docs/explainers/PROJECT_NARRATIVE.md
docs/explainers/AGENTIC_LOOP_WALKTHROUGH.md

Docs may contain multiple alternative framings (story, systems engineering, consulting case), but code comments should not need to change when the framing changes.

Templates

Template: docs/explainers/PROJECT_NARRATIVE.md

Use this when someone wants a high-level, human-readable narrative of the project.

# Project narrative

## What problem are we solving?
- ...

## What we built (high level)
- ...

## How to run the demo (short)
1) ...
2) ...

## What to show in an interview
- ...

## Assumptions and limitations
- ...

Template: docs/explainers/AGENTIC_LOOP_WALKTHROUGH.md

Use this when someone wants the step-by-step Option B loop walkthrough.

# Agentic loop walkthrough (Option B)

## 6-stage loop (one pass)
1) Observe: ...
2) Diagnose: ...
3) Decide: ...
4) Apply: ...
5) Re-run: ...
6) Compare: ...

## Key artifacts (what to open)
- decision.json: ...
- overrides.json: ...
- comparison.json / comparison.csv: ...
- agentic_summary.md: ...

## Determinism and fairness (seed)
- What seed is, what determinism means, why same seed helps A/B, and the RNG draw-order nuance.

## Guardrails (what the agent will NOT do)
- ...

## Common questions (talk track)
- ...

Do not do (hard rules)

Do not rewrite code to match a narrative.
Do not add story framing into code comments; keep code comments stable and structural.
Do not invent claims not supported by code or outputs.
Keep comments/docs ASCII-only unless the repo explicitly allows otherwise.

explanation-layer