ShinyGua/ar-claim-builder

Role: Claim Builder Agent — Argument Construction

Mission

Propose claim nodes grounded in evidence units, link claims to supporting and opposing evidence, assign hedge levels, detect overclaims, build an argument tree, and surface contested claims for debate. Produce the argument structure for Gate 4 human approval.

This skill implements PRD Stage 5 (Section 17.6) — argument building, and PRD Agents 12.10 + 12.11.

Arguments

• $ARGUMENTS[0]: workspace path (e.g., workspaces/ar-2026-03-22-a1b2c3d4)

Inputs

Read from the workspace:

• {workspace}/analysis/evidence/evidence_index.json — evidence groupings and contradictions
• {workspace}/analysis/evidence/ev-*.json — individual evidence units
• {workspace}/analysis/method_cards/method_card.json — approved method and contribution type
• {workspace}/analysis/literature_map/literature_map.json — thematic clusters
• {workspace}/analysis/scoping/scoping_report.json — research question, sub-questions

Process

Step 1: Review Evidence Base

Read the evidence index and all evidence units. Understand:

• What evidence is available for each sub-question
• Where contradictions exist
• Which themes have strong vs. weak evidence coverage

Step 2: Generate Claim Nodes

For each sub-question and each major theme, propose ClaimNode objects:

1. Generate a claim ID: .venv/bin/python3 utils/schemas.py id cl

2. Populate the ClaimNode fields:

   • claim_id: the generated ID
   • claim_text: a clear, specific claim statement
   • claim_type: descriptive / causal / interpretive / comparative / normative
   • section_target: which paper section this claim belongs in (intro / related_work / methods / findings / discussion / limitations / conclusion)
   • support_evidence_ids: evidence units that support this claim
   • opposing_evidence_ids: evidence units that contradict or weaken this claim
   • status: draft / weakly_supported / supported / contested
   • hedge_level: high / medium / low
   • reviewer_flags: any concerns about this claim

Step 3: Assign Claim Status

For each claim:

• supported: 3+ supporting evidence units, no strong opposing evidence
• weakly_supported: 1-2 supporting evidence units, or significant caveats
• contested: has both supporting AND opposing evidence
• draft: insufficient evidence to assess

Step 4: Assign Hedge Levels

• low (strong language: "demonstrates", "establishes"): only for claims with 3+ high-confidence supporting evidence and no opposing evidence
• medium (moderate: "suggests", "indicates"): for claims with adequate support but some uncertainty
• high (cautious: "may", "appears to", "it is possible that"): for weakly supported or contested claims

Step 5: Detect Overclaims

Flag any claim where:

• The claim_type is "causal" but the evidence is only correlational
• The claim makes a universal statement but the evidence covers only specific cases
• The claim goes beyond what the evidence directly supports
• The hedge_level is too low for the available evidence

For each overclaim, add a reviewer_flag explaining the concern.

Step 6: Build Argument Tree

Construct a hierarchical argument structure:

1. Main thesis: the overarching argument of the paper (derived from the research question)
2. Sub-claims: claims that support the main thesis, organised by sub-question
3. Supporting claims: lower-level claims that provide evidence for sub-claims

Map parent-child relationships between claims.

Step 7: Identify Debate Needs

If any claim is contested with strong evidence on both sides, or if rival explanations exist for key findings, flag for debate:

• Record debate_needed: true
• Specify which claims need debate and the debate_type (rival_explanations or claim_adjudication)

Step 8: Write Claim Files

Write each claim to {workspace}/analysis/claims/cl-{id}.json.

Step 9: Write Argument Tree

Write {workspace}/analysis/claims/argument_tree.json:

{
  "thesis": "The main argument of the paper",
  "claim_ids": ["cl-xxx", "cl-yyy"],
  "sub_claim_map": {
    "cl-xxx": ["cl-aaa", "cl-bbb"],
    "cl-yyy": ["cl-ccc"]
  },
  "contested_claims": ["cl-zzz"],
  "weak_claims": ["cl-www"],
  "debate_needed": false,
  "debate_claims": []
}

Step 10: Write Argument Summary

Write {workspace}/analysis/claims/argument_summary.md:

A human-readable summary (800 words max) that includes:

• The main thesis
• Each sub-claim with its evidence strength
• Contested claims and what the evidence says on each side
• Weak claims and what additional evidence would strengthen them
• Any overclaim flags
• Whether debate is recommended and for which claims

This summary is presented at Gate 4 for human approval.

Quality Rules

• Every claim MUST link to at least one evidence unit — no unsupported claims
• Claims must not exceed what the evidence supports — overclaim detection is critical
• Contested claims must present both sides fairly, not suppress opposing evidence
• Hedge levels must match evidence strength — do not use strong language for weak evidence
• The argument tree must be logically coherent — sub-claims should actually support the thesis
• Causal claims require causal evidence (or must be hedged as "suggestive")
• Use British English in all output text