From gaia
Generates complete README for Gaia knowledge packages: fills narrative from reasoning graph skeleton, beliefs, and outline, then pushes to GitHub.
npx claudepluginhub siliconeinstein/gaia --plugin gaiaThis skill uses the workspace's default tool permissions.
Generate a complete README for a Gaia knowledge package and push it to the GitHub repo.
Generates browsable Obsidian wiki vault from Gaia knowledge package: skeleton structure, rewritten rich claim/section pages, cross-reference audits.
Scans Python ML experiment repos to generate hierarchical paper outlines (H1/H2/H3) with user approval checkpoints at each level, then body text with evidence annotations, citations, and bilingual output.
Structures complex domain knowledge into self-contained Markdown packages with multiple reading paths, time budgets, reader roles, and verification tracking for research topics.
Share bugs, ideas, or general feedback.
Generate a complete README for a Gaia knowledge package and push it to the GitHub repo.
gaia render . --target github # Step 1: generate skeleton + narrative outline
/gaia:publish # Step 2: this skill fills narrative + pushes
Run in the package directory (requires gaia compile and gaia infer to have been run first):
gaia render . --target github
This produces .github-output/ containing:
README.md — skeleton with Mermaid reasoning graph, MI annotation, conclusions table, and placeholdersnarrative-outline.md — auto-generated writing backbone (sections grouped by graph connectivity)manifest.json — checklist of exported conclusions and placeholdersImportant: Only copy the skeleton to README.md the FIRST time. On subsequent runs, read the new .github-output/ data (beliefs, outline) but do NOT overwrite the existing README — update it in place.
Primary inputs (drive the narrative):
cat .github-output/narrative-outline.md # Writing backbone from graph structure
cat .github-output/manifest.json # Exported conclusions list
cat .gaia/beliefs.json # BP results
cat .github-output/docs/public/data/graph.json # Figure metadata + graph data
ls src/<package>/*.py # DSL source code (claims, strategies, reasons)
Optional — read artifacts/ (original paper, figures) for factual grounding (equations, experimental numbers, figure context). But be careful: the README is an analysis driven by the reasoning graph, not a paper summary. The graph may assign low belief to claims the paper presents confidently, or reveal structural weaknesses the paper glosses over. Trust the graph's assessment over the paper's rhetoric.
The README must start with a proper citation of the original source material. Read pyproject.toml for the description, and the DSL source's module docstring or artifacts/ for full bibliographic details.
# Package Title
> **Original work:** [Author1, Author2, et al.] "[Paper Title]." *Journal Name* Volume, Pages (Year). [DOI/arXiv link]
[badges]
> [!NOTE]
> This README is an AI-generated analysis based on a [Gaia](https://github.com/SiliconEinstein/Gaia) reasoning graph formalization of the original work. Belief values reflect the graph's probabilistic assessment of each claim's support, not the original authors' confidence. See [ANALYSIS.md](ANALYSIS.md) for detailed verification results.
The agent should find authors, title, journal from the package's pyproject.toml description, module docstrings, or artifacts/paper.md. This citation is used for figure attributions later.
Replace <!-- badges:start --><!-- badges:end --> with links to Pages and Wiki if they exist.
One paragraph (3-5 sentences) readable by any scientist:
The skeleton includes a [!TIP] callout with the total mutual information and a Mermaid reasoning graph. Keep both as generated.
Add ## Reasoning Structure after the Mermaid graph. This is the heart of the README — a per-conclusion evidence assessment. For each exported conclusion, analyze how well the evidence supports it.
Audience: A researcher in the paper's field who has NOT read the original paper. After reading this section, they should understand what each conclusion claims, how it was derived, how strong the evidence is, and what risks remain.
Ordering: Follow narrative-outline.md — this orders conclusions by the paper's logical arc (from foundational results to final predictions), NOT by belief value. The narrative flow should mirror the paper's argument: theory → computation → validation → predictions.
For each conclusion, write:
Heading: Rewrite the claim title into a descriptive sentence that a non-specialist can understand, plus belief value. Don't use the raw label — write a meaningful title.
### Downfolded BSE (belief: 0.33)### The full Bethe-Salpeter equation reduces to a solvable frequency-only form (belief: 0.33)What it says (1 paragraph): Explain the scientific result in enough detail that a reader unfamiliar with the paper can understand it. Include:
artifacts/ for specific details — don't write generic descriptionsEvidence chains (2-4 bullet points): Each evidence chain supporting this conclusion:
Figures: Embed relevant figures from artifacts/images/ with descriptive captions
Verdict (1-2 sentences): Is this conclusion well-supported? What's the main risk?
Example:
### The full Bethe-Salpeter equation reduces to a solvable frequency-only form (belief: 0.33)
The central theoretical achievement of this work is a rigorous
"downfolding" of the complete momentum-frequency Bethe-Salpeter
equation into a one-dimensional integral equation depending only
on Matsubara frequency: $K(\omega,\omega') = \lambda(\omega,\omega')
- \mu_{\omega_c}(\omega,\omega')$. This is accomplished by
decomposing the pair propagator into coherent and incoherent parts
(an exact mathematical identity), then showing that cross-channel
mixing between Coulomb and phonon sectors is suppressed at
$O(\omega_c^2/\omega_p^2) \leq 1\%$. The resulting equation gives
$\mu^\ast$ and $\lambda$ precise microscopic definitions for the
first time — replacing the phenomenological parameters used since
the 1960s. Numerical validation against the full BSE on a toy model
with aluminum-like parameters shows 0.2% agreement in predicted $T_c$.
**Evidence support:**
- **Cross-term suppression** (weakest link, belief 0.50): The entire
downfolding rests on cross-channel terms being ~1%. The estimate
uses a plasmon-pole model that may overstate the suppression for
low-density metals or 2D systems.
- **Toy model validation** (belief 0.76): Full vs downfolded BSE
agree at 0.2%, but this uses RPA for the electron vertex — not
the exact vertex function.

*The BSE with decomposed pair propagator. Adapted from Cai et al.*
> This is the theoretical foundation for everything downstream.
> The low belief (0.33) reflects uncertainty propagation from the
> cross-term suppression assumption — if cross terms are larger
> than 1%, the entire framework needs revision.
The good version explains the science in detail, gives context (why this matters, what existed before), includes the specific mathematical result, and makes the verdict meaningful.
What NOT to do:
Focus: internal nodes with low belief — NOT the conclusions themselves (those are covered in Reasoning Structure). Discuss intermediate claims and premises where the argument is structurally weak.
Write 3-5 weak points, each as a full paragraph:
Executive summary (1 sentence): The single weakest internal link.
For each weak point — an intermediate or hole claim with low belief:
Structural patterns: Are there bottleneck nodes that many conclusions depend on? Does uncertainty amplify through the chain?
Cite belief values parenthetically. Frame as scientific critique, not graph analysis.
Group by theme:
Experimental gaps:
Computational gaps:
Theoretical gaps:
For each gap, name which conclusions would improve if it were filled. Prioritize by impact.
If the package has an ANALYSIS.md (generated during formalization Pass 5/6), add a final section linking to it:
## Detailed Analysis
For structural integrity verification (Pass 5), standalone readability checks (Pass 6),
and complete package statistics, see [ANALYSIS.md](ANALYSIS.md).
Before pushing, verify the README renders correctly:
# Quick check: search for unfilled placeholders
grep -n "<!-- " README.md
# Preview in terminal (if glow is installed)
glow README.md
# Or open in browser
open README.md # macOS
Verify:
<!-- ... --> placeholder comments remaingaia render . --target docs
This writes docs/detailed-reasoning.md with per-module Mermaid reasoning graphs and full claim details. Add a [!NOTE] callout in the README after the overview Mermaid graph:
> [!NOTE]
> **[Per-module reasoning graphs with full claim details →](docs/detailed-reasoning.md)**
>
> 6 Mermaid diagrams (one per section) with every claim, strategy, and belief value.
git add README.md ANALYSIS.md docs/detailed-reasoning.md
git commit -m "docs: update README via /gaia:publish"
git push origin main
Optionally also push wiki and Pages template:
cp -r .github-output/wiki .
cp -r .github-output/docs .
git add wiki/ docs/
git commit -m "docs: add wiki pages and GitHub Pages template"
git push origin main