[barkhagvalani]

Draft: waiting for design-ready on #214. I'll mark this ready for review once the issue is labeled.

Refs #214

Suggested label: docs

Contribution Type

Please select the track that matches this pull request:

• Bug Fix / Minor Patch (Targeted fix, non-test diff <= 100 lines and < 3 core files in skills/ or agents/; no design doc required)
• Feature / Architectural Change -- Stage 1: Design Doc PR (Refs #214 | Adds docs/designs/explain.md and updates docs/designs/README.md)
• Feature / Architectural Change -- Stage 2: Implementation PR

Summary of Key Changes

• docs/designs/explain.md: the design for /egm-explain, a skill run after /egm-bootstrap that writes a plain-language EXPLAINER.md beside each meaningful README contract, plus a repository explainer with a shared glossary. Explainers are built only from contracts (never from code), carry Mermaid diagrams where they help, record their contract's hash for incremental refresh, and are checked by a fact-checker and the egm-comprehension persona.
• docs/designs/README.md: registers the design after the bootstrap row.

The design includes results from a trial run on a production app (20 contracts → 15 explainers, 5 folded; 39 fact-check corrections) and the eight design changes that run produced. A working implementation exists and passes tests/unit against EGM 0.1.0; I'll open it as the Stage 2 PR once this design is merged.

The three open questions from #214 are repeated at the end of the doc.

Human Accountability Affirmation

• I am a human contributor. I have personally reviewed, understood, and can explain every line of this change in review (using AI tools to write code is welcome, but human understanding of the submitted change is required).

Verification

• For Design Doc PRs (Stage 1): Executed /egm-review docs/designs/explain.md, resolved findings via /egm-resolve, and verified relative links (pytest tests/unit/test_link_integrity.py).
• For Bug Fix / Implementation PRs (Stage 2): Unit tests or test_scenarios.yaml added/updated and pytest tests/unit executed.
• For Harness Support PRs: Verified plugin installation and end-to-end execution of /egm-brainstorm, /egm-draft, and /egm-review on the target harness; attached execution summary or transcript.

🤖 Generated with Claude Code

[google-cla]

Thanks for your pull request! It looks like this may be your first contribution to a Google open source project. Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA).

View this failed invocation of the CLA check for more information.

For the most up to date status, view the checks section at the bottom of the pull request.

[n3wth]

Updated in 89d4d08: refresh now invalidates on child explainers, extra-source content, and output settings, including internal-to-shareable audience changes. Goldfish reviewers return findings read-only; the coordinator applies supported fixes. Synced current main and validated the revised design with all 138 offline unit tests plus git diff --check. Draft status is retained. Design-ready on #214 and the three listed maintainer decisions remain outstanding; this update does not claim a native skill implementation or rerun of /egm-review.