Argumentation

---
name: argumentation
locale: caveman-ultra
source_locale: en
source_commit: 82c77053
fence_basis_commit: 82c77053
translator: "Julius Brussee homage — caveman"
translation_date: "2026-04-19"
description: >
  Construct well-structured arguments using the hypothesis-argument-example
  triad. Covers formulating falsifiable hypotheses, building logical arguments
  (deductive, inductive, analogical, evidential), providing concrete examples,
  and steelmanning counterarguments. Use when writing or reviewing PR descriptions
  that propose technical changes, justifying design decisions in ADRs, constructing
  substantive code review feedback, or building a research argument or technical
  proposal.
license: MIT
allowed-tools: Read Write Edit Bash Grep Glob
metadata:
  author: Philipp Thoss
  version: "1.0"
  domain: general
  complexity: intermediate
  language: multi
  tags: argumentation, reasoning, hypothesis, logic, rhetoric, critical-thinking
---

# Construct Arguments

Build rigorous arguments hypothesis → reasoning → concrete evidence. Triad: hypothesis = *what* you believe, argument = *why* holds, examples = *that* holds. Apply to code reviews, design decisions, research writing, any ctx w/ claims needing justification.

## Use When

- Writing/reviewing PR desc proposing technical change
- Justifying design decision in ADR
- Code review feedback beyond "I don't like this"
- Research argument or technical proposal
- Challenge/defend approach in technical discussion

## In

- **Required**: Claim or position needing justification
- **Required**: Context (code review, design decision, research, doc)
- **Optional**: Audience (peer devs, reviewers, stakeholders, researchers)
- **Optional**: Counterarguments or alternative positions
- **Optional**: Evidence or data available

## Do

### Step 1: Formulate Hypothesis

Clear, falsifiable claim. Not opinion or preference — specific assertion testable vs evidence.

1. Claim in 1 sentence
2. Falsifiability test: can someone prove wrong w/ evidence?
3. Scope narrowly: specific ctx, codebase, domain
4. Distinguish from opinions → testable criteria

**Falsifiable vs unfalsifiable:**

| Unfalsifiable (opinion)              | Falsifiable (hypothesis)                                       |
|---|---|
| "This code is bad"                   | "This function has O(n^2) complexity where O(n) is achievable" |
| "We should use TypeScript"           | "TypeScript's type system will catch the class of null-reference bugs that caused 4 of our last 6 production incidents" |
| "The API design is cleaner"          | "Replacing the 5 endpoint variants with a single parameterized endpoint reduces the public API surface by 60%" |
| "This research approach is better"   | "Method A achieves higher precision than Method B on dataset X at the 95% confidence level" |

**→** 1-sentence hypothesis specific + scoped + falsifiable. Reader immediately imagines evidence confirming/refuting.

**If err:** Vague → "how would I disprove?" test. Can't imagine counter-evidence → opinion not hypothesis. Narrow scope or add measurable criteria.

### Step 2: ID Argument Type

Logical structure for hypothesis. Diff claims need diff reasoning strategies.

1. Review 4 types:

| Type        | Structure                                  | Best for                          |
|---|---|---|
| Deductive   | If A then B; A true; therefore B        | Formal proofs, type safety |
| Inductive   | Observed pattern N cases; therefore likely | Perf data, test results    |
| Analogical  | X similar to Y relevant ways; Y has P; therefore X likely P | Design decisions, tech choices |
| Evidential  | E more likely under H1 than H2; therefore H1 supported | Research findings, A/B results |

2. Match hypothesis → strongest type:
   - *must* be true → **deductive**
   - *tends* to be true via observations → **inductive**
   - *will likely work* via similar prior cases → **analogical**
   - one explanation *fits data better* → **evidential**

3. Combine types for stronger arguments (analogical + inductive evidence)

**→** Chosen type (or combo) + clear rationale why fits hypothesis.

**If err:** No single type fits cleanly → split hypothesis into sub-claims. Each w/ natural argument structure.

### Step 3: Construct Argument

Logical chain connecting hypothesis → justification.

1. State premises (facts/assumptions starting from)
2. Show logical connection (premises → conclusion)
3. Steelman strongest counterargument — state best opposing *before* refuting
4. Address counterargument directly w/ evidence or reasoning

**Worked example — Code Review (deductive + inductive):**

> **Hypothesis**: "Extracting validation logic into shared module will reduce bug duplication across 3 API handlers."
>
> **Premises**:
> - 3 handlers (`createUser`, `updateUser`, `deleteUser`) impl same input valid. w/ slight variations (observed `src/handlers/`)
> - Last 6 months, 3/5 valid. bugs fixed in 1 handler not propagated (issues #42, #57, #61)
> - Shared modules enforce single src of truth (deductive: if one impl, then one place to fix)
>
> **Logical chain**: Because 3 handlers duplicate same valid. (premise 1), bugs fixed in 1 missed in others (premise 2, inductive from 3/5). Shared module → fixes apply once to all callers (deductive from shared-module semantics). Therefore extraction reduces bug duplication.
>
> **Counterargument (steelmanned)**: "Shared modules introduce coupling — change to valid. for 1 handler could break others."
>
> **Rebuttal**: Handlers already share identical valid. *intent*; coupling implicit + harder to maintain. Making explicit via shared module w/ parameterized options (`validate(input, { requireEmail: true })`) makes coupling visible + testable. Current implicit duplication riskier — hides dependency.

**Worked example — Research (evidential):**

> **Hypothesis**: "Pre-training on domain-specific corpora improves downstream task perf more than increasing general corpus size for biomedical NER."
>
> **Premises**:
> - BioBERT pre-trained on PubMed (4.5B words) outperforms BERT-Large on general English (16B words) on 6/6 biomedical NER benchmarks (Lee et al., 2020)
> - SciBERT pre-trained on Semantic Scholar (3.1B words) outperforms BERT-Base on SciERC + JNLPBA despite smaller pre-training corpus
> - General-domain scaling (BERT-Base → BERT-Large, 3x params) smaller gains on biomedical NER than domain adaptation (BERT-Base → BioBERT, same params)
>
> **Logical chain**: Evidence consistently shows domain corpus selection outweighs scale for biomedical NER (evidential: these results more likely if domain specificity > scale). 3 independent comparisons same direction → strengthens inductive case.
>
> **Counterargument (steelmanned)**: "Results may not generalize beyond biomedical NER — biomedicine has unusually specialized vocab inflating domain-adaptation advantage."
>
> **Rebuttal**: Valid limitation. Hypothesis scoped biomedical NER specifically. Similar gains appear legal NLP (Legal-BERT) + financial NLP (FinBERT) → pattern may generalize to other specialized domains, separate claim needing its own evidence.

**→** Complete argument chain + premises + logical connection + steelmanned counterargument + rebuttal. Reader follows step by step.

**If err:** Argument weak → check premises. Weak args stem from unsupported premises not faulty logic. Find evidence per premise or acknowledge as assumption. Counterargument stronger than rebuttal → hypothesis needs revision.

### Step 4: Concrete Examples

Support w/ independently verifiable evidence. Not illustrations — empirical foundation making argument testable.

1. ≥1 **positive example** confirming hypothesis
2. ≥1 **edge case/boundary example** testing limits
3. Each **independently verifiable**: another person can reproduce or check no relying on your interpretation
4. Code claims → specific files, line nums, commits
5. Research claims → specific papers, datasets, experimental results

**Example selection criteria:**

| Criterion              | Good example                                        | Bad example                              |
|---|---|---|
| Independently verifiable | "Issue #42 shows the bug was fixed in handler A but not B" | "We've seen this kind of bug before"     |
| Specific               | "`createUser` at line 47 re-implements the same regex as `updateUser` at line 23" | "There's duplication in the codebase"    |
| Representative         | "3 of 5 validation bugs in the last 6 months followed this pattern" | "I once saw a bug like this"             |
| Includes edge cases    | "This pattern holds for string inputs but not for file upload validation, which has handler-specific constraints" | (no limitations mentioned)               |

**→** Concrete examples reader can verify independently. ≥1 positive + 1 edge case. Each refs specific artifact (file, line, issue, paper, dataset).

**If err:** Examples hard to find → hypothesis too broad or not grounded observable reality. Narrow scope → what you can actually point to. Absence = signal, not gap to paper over.

### Step 5: Assemble Complete Argument

Combine hypothesis + argument + examples → appropriate format for ctx.

1. **Code reviews** — structure:
   ```text
   [S] <one-line summary of the suggestion>

   **Hypothesis**: <what you believe should change and why>

   **Argument**: <the logical case, with premises>

   **Evidence**: <specific files, lines, issues, or metrics>

   **Suggestion**: <concrete code change or approach>
   ```

2. **PR descriptions** — body:
   ```markdown
   ## Why

   <Hypothesis: what problem this solves and the specific improvement claim>

   ## Approach

   <Argument: why this approach was chosen over alternatives>

   ## Evidence

   <Examples: benchmarks, bug references, before/after comparisons>
   ```

3. **ADRs (Architecture Decision Records)** — std ADR format + triad → Context (hypothesis), Decision (argument), Consequences (examples/evidence of expected outcomes)

4. **Research writing** — std structure: Intro = hypothesis, Methods/Results = argument + examples, Discussion = counterarguments

5. Review assembled for:
   - Logical gaps (conclusion follow from premises?)
   - Missing evidence (unsupported premises?)
   - Unaddressed counterarguments (strongest objection answered?)
   - Scope creep (stays within hypothesis bounds?)

**→** Complete formatted argument appropriate for ctx. Reader can eval hypothesis, follow reasoning, check evidence, consider counterarguments — all in 1 coherent structure.

**If err:** Assembled feels disjointed → hypothesis too broad. Split into focused sub-arguments, each w/ own triad. 2 tight > 1 sprawling.

## Check

- [ ] Hypothesis falsifiable (could disprove w/ evidence)
- [ ] Hypothesis scoped specific ctx, not universal
- [ ] Argument type ID'd + appropriate for claim
- [ ] Premises stated explicitly, not assumed shared knowledge
- [ ] Logical chain connects premises → conclusion no gaps
- [ ] Strongest counterargument steelmanned + addressed
- [ ] ≥1 positive example supports
- [ ] ≥1 edge case or limitation acknowledged
- [ ] All examples independently verifiable (refs provided)
- [ ] Out format matches ctx (code review, PR, ADR, research)
- [ ] No logical fallacies (appeal to authority, false dichotomy, strawman)

## Traps

- **State opinions as hypotheses**: "This code is messy" = preference not hypothesis. Rewrite testable: "This module has 4 responsibilities that should be separated per single-responsibility principle, as evidenced by 6 public methods spanning 3 unrelated domains."
- **Skip counterargument**: Unaddressed objections weaken even if reader never voices. Always steelman — state strongest opposing in best form before rebutting.
- **Vague examples**: "We've seen this pattern" not evidence. Point to specific issues, commits, lines, papers, datasets. Can't find concrete → hypothesis not well-grounded.
- **Argument from authority**: "Senior engineer said so" or "Google does it this way" not logical argument. Authority *motivates* investigation; argument must stand on evidence + reasoning.
- **Scope creep in conclusions**: Drawing broader than evidence supports. Examples cover 3 API handlers → don't conclude about entire codebase. Match conclusion scope → evidence scope.
- **Conflate argument types**: Inductive lang ("tends to") for deductive ("must be") or vice versa. Precise about strength — deductive = certainty, inductive = probability.

## →

- `review-pull-request` — apply argumentation → structured code review feedback
- `review-research` — evidence-based arguments in research
- `review-software-architecture` — justify architectural decisions via triad
- `create-skill` — skills = structured arguments for how to accomplish task
- `write-claude-md` — doc conventions + decisions benefiting from clear justification

### Composition: Argumentation + Advocatus Diaboli

High-stakes decisions → compose w/ `advocatus-diaboli` agent → pre-decision review loop:

1. **Structure** via argumentation — build triad
2. **Stress-test** via advocatus-diaboli — steelman proposal, challenge each assumption w/ specific questions. Severity: Critical (redesign/abandon), Medium (adjust), Low (note + proceed)
3. **Revise** per findings — critical → redesign; medium → adjustment; low → noted

**When compose vs alone:**
- Argumentation alone → constructing proposal, PR desc, design justification
- Advocatus-diaboli alone → reviewing someone else's existing argument
- Compose both → you're both proposer + need adversarial self-review pre-committing

**Example — PR response refinement:**
Argumentation structured response (hypothesis: combining PRs better, argument w/ evidence, collaboration offer). Advocatus-diaboli caught 2 critical issues: claim about proxy proc ID speculative not factual (would've been embarrassing on security PR), "I have tested this in practice" unverifiable. Both removed. Final 40-50% shorter — overexplaining signals insecurity.

**Example — System design triage:**
Argumentation (via Plan agent) designed full 500-line triage pipeline. Advocatus-diaboli killed: at 9 items, premature + system itself would become maintenance burden (recursive trap). Final: 25 lines added to existing script.