notque/vexjoy-agent / skills/content/writing
writing
UnverifiedWriting: voice creation and validation, prose editing, anti-AI cleanup, professional communication, translation.
references/technical-journalist-writer/sourcing-and-claims.md
View on GitHub# Sourcing and Claims Patterns
> **Scope**: How to handle factual claims, mark inferences, cite sources, and avoid unsupported assertions in technical journalism. Covers claim classification and detection commands for validation.
> **Version range**: All versions — applies to any technical article output.
> **Generated**: 2026-04-15
---
## Overview
The journalist voice requires a verifiable basis for every factual claim. The agent body includes a hard STOP rule: before delivering any article, verify every factual claim against its source. This reference operationalizes that rule — covering claim classification, inline citation patterns, how to mark inferences, and how to detect unsupported assertions.
---
## Claim Classification
| Claim Type | Source Required | How to Handle |
|------------|----------------|---------------|
| Statistical claim | Yes — specific source | Cite inline: "X% of Y, per [Source Year]" |
| Version-specific behavior | Yes — release notes or docs | Cite inline: "as of [Framework vX.Y]" |
| Historical event | Yes — dated reference | Cite with date: "in [Month Year], [Organization]..." |
| Architectural observation | If specific — docs or codebase | Mark as inference if derived from reading code |
| General mechanism | No — established knowledge | State directly without citation |
| Reader-facing inference | No source exists — reasoning only | Mark explicitly: "this suggests..." or "the implication is..." |
---
## Correct Sourcing Patterns
### Statistical Claims
State the source inline, not in a footnote. Technical readers verify claims immediately.
```markdown
PostgreSQL handles approximately 10,000 concurrent connections on typical hardware,
per the 2023 PostgreSQL benchmark suite. The limit is configurable via max_connections.
```
```markdown
The study found 73% of production incidents traced to configuration drift,
not code bugs (Puppet State of DevOps Report, 2022).
```
**Why inline**: Footnotes require the reader to interrupt reading to verify. Inline sourcing integrates verification into reading.
---
### Version-Specific Behavior
State the version where behavior applies or changed.
```markdown
Go 1.21 introduced built-in min/max functions. Prior versions required
manual comparison or a third-party package.
```
```markdown
React 18 changed rendering to concurrent by default. Strict Mode behavior
changed as a result — effects run twice in development.
```
**Detection** — version claims without version number:
```bash
# Claims about framework behavior without version qualifier
rg '\b(changed|introduced|deprecated|removed|added)\b' article.md | grep -v '\b[0-9]\+\.[0-9]\+\b'
```
---
### Marking Inferences
When a claim derives from reasoning rather than a direct source, mark it explicitly.
**Marked inference patterns** (acceptable):
```markdown
The latency increase suggests the bottleneck is in the serialization layer,
not the network hop.
This implies that the migration runs before the application starts — otherwise
the schema version check would fail on startup.
The configuration suggests the team chose consistency over availability
in the CAP tradeoff.
```
**Unmarked inference patterns** (wrong — these sound like facts):
```markdown
The bottleneck is in the serialization layer. # stated as fact, is inference
The migration runs before the application starts. # stated as fact, is inference
```
---
<!-- no-pair-required: section-header-only — catalog heading, individual blocks carry the do-framing -->
## Pattern Catalog
### Cite Sources for Statistical Claims
**Detection**:
```bash
# Percentage claims without citation signal
rg '\b[0-9]+%\b' article.md | grep -v 'per\|according\|source\|report\|survey\|study\|2[0-9][0-9][0-9]'
# Numeric comparative claims ("X times faster", "X% improvement")
rg '\b[0-9]+ times (faster|slower|larger|smaller)\b' article.md
```
**Signal**:
```
Studies show that 80% of developers prefer this approach. It's 3x faster
than the alternative in most workloads.
```
**Why this matters**: "Studies show" without a specific study is not a source — it's a rhetorical move. "3x faster" without a benchmark methodology is marketing language. Both patterns erode credibility when readers verify them and find nothing.
**Preferred action:**
```
The Redis Labs 2023 benchmark showed 3.2x throughput improvement over
Memcached for workloads with key sizes under 1KB. Results vary with
key distribution and value size.
```
---
### Mark Inferences as Inferences
**Detection**:
```bash
# Definitive statements about system internals that would require source code to verify
rg '\b(definitely|certainly|always|never|guaranteed|impossible)\b' article.md
# "The reason is..." patterns (often inference stated as fact)
rg '\b(the reason (is|was|for)\b|this is because\b|this happens because\b)' article.md -i
```
**Signal**:
```
The reason the system is slow is definitely the database. The query
always takes 200ms because of missing indexes.
```
**Why this matters**: Without profiling data or execution plans, this is inference stated as fact. If the reader checks and the database isn't the bottleneck, the article loses all credibility.
**Preferred action:**
```
Profiling showed the database at 73% of request time. The slow_query_log
identified three queries averaging 200ms — all on the users table without
an index on created_at.
```
Or, if no profiling data is available:
```
The symptoms suggest database contention — high response time with low CPU
usage typically indicates waiting on I/O or locks, not compute.
```
---
### Date All Historical Claims
**Detection**:
```bash
# Historical claims without a year
rg '\b(originally|previously|historically|in the early days|back when|used to)\b' article.md | grep -v '\b(19|20)[0-9][0-9]\b'
# "When X was released/launched/introduced" without year
rg 'when .* (was released|launched|introduced|shipped)' article.md -i | grep -v '\b(19|20)[0-9][0-9]\b'
```
**Signal**:
```
When Kubernetes was first released, the networking model was much simpler.
Originally, services used flat networks without namespace isolation.
```
**Why this matters**: "When Kubernetes was first released" is vague — Kubernetes 1.0 shipped July 2015. Without the date, the reader can't evaluate how much the ecosystem has changed since then.
**Preferred action:**
```
Kubernetes 1.0 shipped in July 2015 with a flat networking model.
NetworkPolicy resources, which enable namespace isolation, arrived in
Kubernetes 1.3 (July 2016).
```
---
### Provide Baselines for Comparative Claims
**Detection**:
```bash
# Comparative claims that require a baseline to be meaningful
rg '\b(better than|worse than|faster than|more reliable than|superior to|more popular than)\b' article.md -i
# "Widely adopted", "commonly used", "most teams" — popularity claims need data
rg '\b(widely|commonly|most teams|most developers|industry standard|best practice)\b' article.md -i
```
**Signal**:
```
PostgreSQL is more reliable than MySQL for write-heavy workloads.
Most teams have moved away from monolithic architectures.
```
**Why this matters**: "More reliable" requires a specific reliability metric and measured workload. "Most teams" requires a survey. Without these, the claims are opinions presented as facts.
**Preferred action:**
```
In TPC-C benchmarks on write-heavy workloads, PostgreSQL's MVCC implementation
shows lower lock contention than MySQL's row-level locking under high concurrency
(PostgreSQL vs MySQL Benchmark, 2023).
The CNCF 2023 Annual Survey found 44% of respondents running microservices
in production, up from 38% in 2022.
```
---
## Inference Marking Cheat Sheet
Use these phrasings to mark inferences explicitly:
| Inference Strength | Phrasing |
|-------------------|----------|
| Strong (high confidence) | "This suggests..." / "The data implies..." |
| Medium | "One explanation is..." / "This may indicate..." |
| Weak (speculative) | "It's possible that..." / "If [assumption] holds, then..." |
| Acknowledged gap | "Without profiling data, the root cause is unclear." |
**Rule**: When you can't point to a source for a claim, either mark it as inference using the above phrasings, or remove it. The third option — stating inference as fact — is not available in this voice.
---
## Detection Commands Reference
```bash
# Unsourced percentage claims
rg '\b[0-9]+%\b' --type md | grep -v 'per\|according\|source\|report\|survey\|study\|2[0-9][0-9][0-9]'
# Version claims without version numbers
rg '\b(changed|introduced|deprecated|removed|added)\b' --type md | grep -v '\b[0-9]\+\.[0-9]\+\b'
# Certainty words on inference statements
rg '\b(definitely|certainly|always|never|guaranteed|impossible)\b' --type md
# Historical claims without year
rg '\b(originally|previously|historically|back when|used to)\b' --type md | grep -v '\b(19|20)[0-9][0-9]\b'
# Comparative claims without baseline
rg '\b(better than|faster than|more reliable than|superior to)\b' --type md -i
```
---
## See Also
- `voice-patterns.md` — banned phrases and tone failure modes
- `article-structure-patterns.md` — structural patterns for explainer/opinion/analysis
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |