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.

code

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

code

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