0xhoneyjar/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)

1. Template for the selected document type:

   • Read: .claude/skills/ground-truth/resources/templates/${DOC_TYPE}.md
   • This defines required sections, provenance expectations, and structure

2. Provenance specification:

   • Read: .claude/skills/ground-truth/resources/provenance-spec.md
   • This defines the exact tag syntax, citation rules, and evidence anchor format

3. Quality gate requirements (know what will be checked):

   • Citation verification: every file:line must 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: ... -->

Tier B: Evidence (load in priority order, within token budget)

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

5. Registry files:

   • Read: grimoires/loa/ground-truth/features.yaml
   • Read: grimoires/loa/ground-truth/limitations.yaml
   • Read: grimoires/loa/ground-truth/capability-taxonomy.yaml

6. Grimoire state (if available):

   • Read: grimoires/loa/NOTES.md
   • Read: grimoires/loa/decisions.yaml (if exists)

7. Voice template:

   • Read: .claude/skills/ground-truth/resources/voice/bridgebuilder-gtm.md

8. Analogy bank (if available):

   • Read: .claude/skills/ground-truth/resources/analogies/analogy-bank.yaml
   • Each analogy has a confidence field (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

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:

1. Read the existing document
2. Only rewrite sections whose headings appear in stale_headings
3. Preserve all non-stale sections byte-for-byte
4. 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

1. Every CODE-FACTUAL paragraph MUST:

   • Be preceded by <!-- provenance: CODE-FACTUAL -->
   • Contain at least one backtick file:line citation
   • 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

2. Every HYPOTHESIS paragraph MUST:

   • Be preceded by <!-- provenance: HYPOTHESIS -->
   • Start with an epistemic marker ("We hypothesize", "We are exploring", etc.)

3. Every EXTERNAL-REFERENCE MUST cite a URL or paper reference

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

5. Banned terms: Never use any term from banned-terms.txt

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

1. Fix the citation, not the claim — find the correct file:line for the real code
2. If the claim is wrong — update both the claim and the citation
3. If a claim cannot be grounded — convert from CODE-FACTUAL to HYPOTHESIS with epistemic marker
4. Never fabricate a citation to make the verifier pass
5. 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.