Code Explainer

See references/output-contract.md for exact artifacts and references/evaluation-rubric.md for the passing bar.

Command

Run from this skill directory:

python scripts/analyze.py analyze \
  --source <local_path_or_github_url> \
  --output <output_dir> \
  --mode <quick|standard|deep> \
  --format <markdown|html|both> \
  --explainer-type <onboarding|project-recap|plan-review|diff-review> \
  --audience <nontech|mixed|engineering> \
  --overview-length <short|medium|long> \
  --since <time_window> \
  --git-ref <ref> \
  --plan-file <path> \
  --include-glob <pattern> \
  --exclude-glob <pattern> \
  --enable-llm-descriptions <true|false> \
  --enable-excalidraw-export <true|false> \
  --enable-official-excalidraw-bridge <true|false> \
  --ask-before-llm-use <true|false> \
  --prompt-for-llm-key <true|false> \
  --persist-llm-key <ask|true|false> \
  --enable-web-enrichment <true|false>

Defaults:

• mode=standard
• format=markdown
• explainer-type=onboarding
• audience=nontech
• overview-length=medium
• enable-llm-descriptions=true
• enable-excalidraw-export=true
• enable-official-excalidraw-bridge=false
• ask-before-llm-use=false
• prompt-for-llm-key=true
• persist-llm-key=ask
• enable-web-enrichment=true

LLM Behavior

• The high-quality path is explanation-first and uses scripts/llm_describe.py.
• The LLM path is the required production path for this skill.
• If CODE_EXPLAINER_LLM_API_KEY or OPENAI_API_KEY is set, the skill can use a live model.
• If no key is available, the skill should prompt for one when the terminal is interactive.
• The user can choose to persist the provided key in a local .env file for future runs.
• CODE_EXPLAINER_MOCK_LLM=true is only for explicit development or offline test scenarios and is not the normal production path.

Workflow

1. Normalize the source and build a repository index.
2. Detect stack, entrypoints, dependencies, flows, and documentation coverage.
3. Build explanation_plan.json with top modules, audience starting points, diagram purposes, and caveats.
4. Generate the narrative layer with LLM or grounded mock/deterministic fallback.
5. Build focused diagrams tied to onboarding questions.
6. Export those diagrams into editable Excalidraw scenes through the deterministic local exporter.
7. Optionally prefer the official Excalidraw bridge only when explicitly enabled for development experiments.
8. Generate overview and deep docs from the explanation plan plus narrative layer.
9. Run fact-check and explanation-quality evaluation.
10. Fail the run if quality gates do not clear the rubric.

Proof Path

Run the shipped self-audit:

python scripts/self_audit.py

This runs the skill on fixture repositories in assets/fixtures/, uses the grounded mock explainer path, and writes proof artifacts under .audit_tmp/code-explainer-self/.

Dependencies

Required:

• Python 3.10+
• Node.js 18+ + npm
• Git when --source is a GitHub URL

Recommended:

• Mermaid CLI (mmdc) from @mermaid-js/mermaid-cli for higher-fidelity diagram rendering
• Node.js is only required for GitHub cloning and optional development-time Excalidraw bridge experiments

Install dependencies:

powershell -ExecutionPolicy Bypass -File .\scripts\install_runtime.ps1

or

bash ./scripts/install_runtime.sh

Notes

• This skill does not mutate the analyzed repository.
• The skill may create or update a local .env file in the skill directory when the user chooses to persist the prompted LLM key.
• If the explanation-quality score is below the rubric threshold, treat the output as failed even if files were produced.
• If Excalidraw export is enabled, treat missing or partial editable scene generation as a real quality issue, not a cosmetic extra.
• The deterministic local Excalidraw exporter is the canonical production path.
• The official @excalidraw/mermaid-to-excalidraw bridge is opt-in only via --enable-official-excalidraw-bridge true and should be treated as a development experiment, not a required runtime dependency.
• Use include/exclude globs to narrow analysis when the repository is very large or noisy.

References

• references/output-contract.md
• references/diagram-style-guide.md
• references/persona-writing-guide.md
• references/mode-behavior.md
• references/evaluation-rubric.md