ground-truth
GitHub基于代码事实生成GTM文档，确保声明可验证、引用真实。通过确定性脚本校验引用和术语，杜绝幻觉。支持能力简报等类型及增量更新模式，强调机制与证据而非营销辞藻。
Trigger Scenarios
Install
npx skills add NeverSight/learn-skills.dev --skill ground-truth -g -y
SKILL.md
Frontmatter
{
"name": "ground-truth",
"agent": "general-purpose",
"context": "fork",
"enhance": false,
"description": "Generate factual, code-grounded GTM documents with BridgeBuilder voice and deterministic verification",
"danger_level": "moderate",
"allowed-tools": "Read, Grep, Glob, Bash(.claude\/scripts\/ground-truth\/*)"
}
Ground Truth — Factual GTM Document Generation
You are generating factual, code-grounded GTM documents using the BridgeBuilder voice. Every claim must be verifiable. Every citation must be real. The verification layer is entirely deterministic — shell scripts check your work. You cannot hallucinate past the firewall.
"Mechanism over adjective. Evidence over assertion. Teaching over selling."
Pre-flight
Check registries exist
for f in features.yaml limitations.yaml capability-taxonomy.yaml; do
if [[ ! -f "grimoires/loa/ground-truth/$f" ]]; then
echo "ERROR: Missing registry: grimoires/loa/ground-truth/$f"
echo ""
echo "Run: .claude/scripts/ground-truth/bootstrap-registries.sh"
echo "Then edit the files and commit before running /ground-truth."
exit 1
fi
done
echo "Registries OK"
Parse arguments
Supported flags:
--type capability-brief(default)--type architecture-overview--incremental— Only regenerate stale sections (v2.0)
DOC_TYPE="${1:-capability-brief}"
OUTPUT_DIR="grimoires/loa/ground-truth"
INCREMENTAL=false
# Parse --incremental flag from arguments
Stage 1: GROUND — Load codebase reality
Load context in priority order. Tier A is non-negotiable.
Tier A: Hard Constraints (load first, always)
-
Template for the selected document type:
- Read:
.claude/skills/ground-truth/resources/templates/${DOC_TYPE}.md - This defines required sections, provenance expectations, and structure
- Read:
-
Provenance specification:
- Read:
.claude/skills/ground-truth/resources/provenance-spec.md - This defines the exact tag syntax, citation rules, and evidence anchor format
- Read:
-
Quality gate requirements (know what will be checked):
- Citation verification: every
file:linemust resolve to a real, tracked file - Banned terms: zero tolerance for superlatives
- Provenance tags: ≥95% coverage, class-specific citation rules enforced
- Evidence anchors: every CODE-FACTUAL paragraph needs
<!-- evidence: ... -->
- Citation verification: every
Tier B: Evidence (load in priority order, within token budget)
-
Code reality — highest priority evidence:
- Read:
grimoires/loa/reality/index.md(if available from /ride) - Or: Run inventory-modules.sh to enumerate modules
- Read actual source files for specific claims
- Read:
-
Registry files:
- Read:
grimoires/loa/ground-truth/features.yaml - Read:
grimoires/loa/ground-truth/limitations.yaml - Read:
grimoires/loa/ground-truth/capability-taxonomy.yaml
- Read:
-
Grimoire state (if available):
- Read:
grimoires/loa/NOTES.md - Read:
grimoires/loa/decisions.yaml(if exists)
- Read:
-
Voice template:
- Read:
.claude/skills/ground-truth/resources/voice/bridgebuilder-gtm.md
- Read:
-
Analogy bank (if available):
- Read:
.claude/skills/ground-truth/resources/analogies/analogy-bank.yaml - Each analogy has a
confidencefield (high/moderate):- high: Use directly — "X works like Y" with full structural comparison
- moderate: Use with qualifier — "in some ways similar to Y" or "loosely parallels Y"
- Staleness of high-confidence analogies is a more urgent signal than moderate ones
- Read:
Token budget
Target: 13,500–28,000 tokens for generation context.
- Tier A: ~3,000 tokens (templates + provenance spec)
- Tier B reality: ~8,000 tokens (code + registries)
- Tier B voice: ~1,500 tokens (voice template + analogies)
- Remaining: generation prompt + output space
If context exceeds budget, truncate Tier B items from lowest priority up.
Stage 2: INVENTORY — Run shell scripts
Run inventory and extraction scripts to gather structured data:
# Module inventory
.claude/scripts/ground-truth/inventory-modules.sh --json
# Limitations extraction
.claude/scripts/ground-truth/extract-limitations.sh --json
Use the Read tool to inspect specific source files for claims you'll make. Do NOT use arbitrary Bash to read files — use the Read tool.
Stage 3: GENERATE — Produce the document
Incremental mode (v2.0)
When --incremental is set, only regenerate sections that are stale:
# Check which sections need regeneration
staleness=$(.claude/scripts/ground-truth/check-staleness.sh "${OUTPUT_DIR}/${DOC_TYPE}.md" --json)
stale_count=$(echo "$staleness" | jq -r '.stale_count')
if [[ "$stale_count" -eq 0 ]]; then
echo "No stale sections — document is current"
# Skip to Stage 6 (OUTPUT)
fi
# Get list of stale section headings
stale_headings=$(echo "$staleness" | jq -r '.stale_sections[].heading')
When regenerating incrementally:
- Read the existing document
- Only rewrite sections whose headings appear in
stale_headings - Preserve all non-stale sections byte-for-byte
- Run VERIFY on the full document after partial regeneration (not just stale sections)
If --incremental is NOT set, generate the full document as before:
Generate the document following the template structure exactly.
Generation rules
-
Every CODE-FACTUAL paragraph MUST:
- Be preceded by
<!-- provenance: CODE-FACTUAL --> - Contain at least one backtick
file:linecitation - Be followed by
<!-- evidence: symbol=X, literal="Y" -->with tokens from the cited range - Use the Read tool to verify the cited lines BEFORE writing the citation
- Be preceded by
-
Every HYPOTHESIS paragraph MUST:
- Be preceded by
<!-- provenance: HYPOTHESIS --> - Start with an epistemic marker ("We hypothesize", "We are exploring", etc.)
- Be preceded by
-
Every EXTERNAL-REFERENCE MUST cite a URL or paper reference
-
BridgeBuilder voice:
- At least 1 FAANG/bluechip analogy per major section (## heading)
- 70/30 rule: 70% mechanism, 30% analogy
- Never force an analogy — prefer omission over inaccuracy
-
Banned terms: Never use any term from
banned-terms.txt -
Citation encoding: Paths must be repo-relative, matching
^[a-zA-Z0-9_./-]+$
Output
Write the generated document to:
grimoires/loa/ground-truth/${DOC_TYPE}.md
Stage 4: VERIFY — Deterministic quality gates
Run the full quality gate suite. No LLM in this path.
.claude/scripts/ground-truth/quality-gates.sh "grimoires/loa/ground-truth/${DOC_TYPE}.md" --json
If exit code is 0: proceed to Stage 6 (OUTPUT). If exit code is 1: proceed to Stage 5 (REPAIR).
Stage 5: REPAIR — Fix verification failures (max 3 iterations)
When quality gates fail, you receive a JSON failure report. Fix each failure.
Repair interface contract
- Input: Failure JSON from quality-gates.sh + the generated markdown draft
- Allowed edits: ONLY the generated markdown at
grimoires/loa/ground-truth/${DOC_TYPE}.md - Method: Full rewrite of the generated markdown file
- Guard: Do NOT edit source code, registries, or any file outside
grimoires/loa/ground-truth/
Repair rules
- Fix the citation, not the claim — find the correct
file:linefor the real code - If the claim is wrong — update both the claim and the citation
- If a claim cannot be grounded — convert from CODE-FACTUAL to HYPOTHESIS with epistemic marker
- Never fabricate a citation to make the verifier pass
- Use the Read tool to inspect actual source files during repair
Repair loop
iteration = 0
while iteration < 3:
Fix failures based on JSON report
Rewrite document
Run quality-gates.sh again
If PASS: break
iteration++
If iteration == 3 and still failing:
HALT with detailed failure report
Save last draft for manual review
After each repair, re-run Stage 4 (VERIFY).
Stage 6: OUTPUT — Write and stamp
After verification passes:
Stamp freshness metadata
.claude/scripts/ground-truth/stamp-freshness.sh "grimoires/loa/ground-truth/${DOC_TYPE}.md"
Confirm output
Report to the user:
- Document path
- Citation count (verified)
- Provenance coverage percentage
- Warning count (if any)
- Generation timestamp
Stage 7: MANIFEST — Update generation manifest
.claude/scripts/ground-truth/write-manifest.sh "grimoires/loa/ground-truth/${DOC_TYPE}.md" \
--citations ${CITATION_COUNT} \
--warnings ${WARNING_COUNT} \
--gates pass
This creates/updates grimoires/loa/ground-truth/generation-manifest.json with:
- Document path, generation timestamp, HEAD SHA
- Citation count, quality gate result, warning count
- Registry SHAs (features, limitations, ride)
Beads Integration (Optional)
If br (beads_rust) is available, track generation as a beads task:
if command -v br &>/dev/null; then
# Create task before generation
br create --label "ground-truth:${DOC_TYPE}" --status in_progress
# On success
br close <task-id> --reason "Generated ${DOC_TYPE} with ${CITATION_COUNT} verified citations"
# On repair loop exhaustion
br update <task-id> --status blocked --comment "Repair loop exhausted after 3 iterations"
fi
If br is not available, skip silently — beads integration is optional.
Error Handling
| Failure | Recovery |
|---|---|
| /ride output missing | Prompt user to run /ride first |
| /ride output stale (>7 days) | Warn user; proceed with stale data or prompt re-ride |
| Registry files missing | Fail fast with bootstrap command |
| Quality gate fails | Enter REPAIR loop (max 3 iterations) |
| Repair loop exhausted | HALT with failure report; save last draft |
| yq not installed | Warn; skip registry-consistency gate |
Circuit Breaker
If the same document type fails verification 3 consecutive times across separate invocations,
log a warning to grimoires/loa/NOTES.md:
## Blockers
- [{date}] ground-truth: {doc-type} failed verification 3 consecutive times.
Last failure: {gate} on {citation}.
Likely cause: /ride reality is stale or features.yaml is out of date.
Action: Re-run /ride and review features.yaml.
Version History
- e0220ca Current 2026-07-05 20:35
