Claims Workflow¶

This page documents how to work with the Claims Registry system, which ensures all factual assertions on the site are properly documented and approved.

Overview¶

The Claims Registry is a safety system that:

1. Tracks all significant factual assertions made on the site
2. Links each claim to primary evidence
3. Requires explicit approval for sensitive claim types
4. Blocks production builds if unapproved claims are referenced

Claim Types¶

Each claim must be classified as one of these types:

Creating a New Claim¶

1. Create the claim file¶

Create a new file in docs/claims/registry/ following this pattern:

CLM-YYYY-NNN.md

Where YYYY is the year and NNN is a sequential number (e.g., the 10th claim of 2025 would be CLM-YYYY-NNN.md → CLM-2025-010.md).

2. Add required frontmatter¶

---
claim_id: CLM-2025-010
title: "Short descriptive title"
claim_text: "Exact claim sentence as it should appear on site"
claim_type: procedural_fact
confidence: high
firmly_established: true
primary_evidence:
  - doc_id: DOC-20251002-001
    relevance: "Why this document supports the claim"
secondary_evidence: []
unknowns:
  - "What evidence is missing"
last_reviewed: 2025-12-21
approval_required: false
approval_status: pending
approved_by: null
approved_at: null
related_pages:
  - /discrepancies/
risk_flags: []
notes: ""
---

3. Determine approval_required¶

Set approval_required: true if ANY of these are true:

• claim_type is characterization, inference, allegation, or opinion
• firmly_established is false
• confidence is not high

4. Add claim body¶

After the frontmatter, add a markdown body explaining:

• What the claim asserts
• The primary evidence supporting it
• Any unknowns or pending information
• Alternative explanations (for characterizations/inferences)

What Counts as "Firmly Established"¶

A claim is firmly established when:

• A reasonable reader can trace it directly to primary documents without interpretive leaps
• It is explicitly stated in a primary source (quoted or cleanly paraphrased), OR
• Multiple primary documents independently confirm the same proposition

A claim is NOT firmly established if:

• It interprets motive or intent
• It depends on allegations without documentary confirmation
• It is a "pattern" claim without enumerated instances
• It reconstructs "what must have happened"
• It depends on private or off-record knowledge

Approving a Claim¶

Only Kevin Bass can approve claims. To approve:

1. Navigate to the claim file in docs/claims/registry/
2. Review:
3. Is the claim_text accurate and appropriately hedged?
4. Is there sufficient primary_evidence?
5. Are unknowns properly documented?
6. Are alternative explanations included (for characterizations)?
7. If approved, update:

   approval_status: approved
   approved_by: "Kevin Bass"
   approved_at: 2025-12-21T10:00:00
   

8. If revisions needed:
9. Edit the claim_text to be more accurate or less assertive
10. Add notes explaining the revision
11. Leave approval_status: pending

Referencing Claims in Pages¶

To reference a claim in an analysis page, use the claim block pattern:

<div class="claim-block established" data-claim-id="CLM-2025-001" markdown>
**Claim:** The characterization of the hearing may not match the documented record.

**Status:** <span class="status-chip produced">Established</span>

**Evidence:** [DOC-20251006-001](/docs/doc-20251006-001/), [DOC-20251007-004](/docs/doc-20251007-004/)

**As of:** 2025-12-21
</div>

Use these status classes:

• established — Green, for approved firmly established claims
• supported — Blue, for approved claims with some evidence
• disputed — Orange, for claims under active dispute
• pending — Gray with "PENDING REVIEW" badge, for unapproved claims

Build-Time Validation¶

The validate_claims.py script runs during builds and checks:

1. All referenced claim IDs exist in the registry
2. All required-approval claims are approved
3. All firmly-established claims have evidence
4. All approved claims have approver metadata

If validation fails:

• Production builds (CLAIM_GATE_MODE=production): Build fails
• Draft builds (CLAIM_GATE_MODE=draft): Warnings only, build continues

Review Queue¶

The Claims Review Queue is auto-generated and shows:

• High-priority claims (with risk flags)
• All pending claims
• Recently approved claims

Check this page regularly to see what needs approval.

Writing Style Guidelines¶

When writing claims, follow these principles:

Do:¶

• Use neutral verbs: "states," "shows," "indicates," "documents"
• Attribute clearly: "According to DOC-...", "The filing states..."
• Hedge appropriately: "may," "appears," "is consistent with"
• Include alternatives: "One interpretation is..., but..."

Don't:¶

• Assert motive or intent without evidence
• Use loaded terms: "fraud," "cover-up," "retaliation" (unless quoting)
• Use intensifiers: "obviously," "clearly," "undeniably"
• State inferences as settled facts

Example: Good vs. Bad Claims¶

Bad:

"TTUHSC lied about the hearing."

Good:

"In [statement/doc], TTUHSC stated X (DOC-...). In [document], Y is stated (DOC-...). These statements are in tension; the record does not establish intent."

Bad:

"They retaliated against him."

Good:

"A filing alleges retaliation (DOC-...). The record documents [sequence of actions] (DOC-...; DOC-...). Whether these actions meet a legal definition is not determined here."

Questions?¶

For questions about the claims system, contact kbassphiladelphia@gmail.com.