"""journalism-writing craft skill — deterministic checks.

Craft drawn from the journalism / argumentation tradition (reporting·explainer·
inverted pyramid·Toulmin·Hegelian dialectic·fairness). It owns the contradiction
theme jrn.* measurements (legacy T4·D1·D5·D6 — Toulmin qualifier·Hegelian dialectic
structure). Many criteria (J1 Lede·J2 Nut graph, etc.) are judge=M (qualitative), so
only the SKILL.md / criteria.json definitions live here and desk reviews them.

content-type-agnostic: the shared section (conflict_section) is extracted and
injected by the orchestrator. The measurement logic was ported verbatim from
contradiction.py `_rubric_metrics` (diff-0).
"""

from __future__ import annotations

import importlib.util as _ilu
import re
from pathlib import Path


# ── dialectic/Toulmin measurement regexes (verbatim from contradiction.py) ──
# Toulmin qualifier phrasings (T4). English-native forms first; the Korean forms
# fire under WIKI_LANG=ko.
QUALIFIER_PATTERNS = [
    re.compile(r"in the short[- ]term", re.IGNORECASE),
    re.compile(r"on this metric", re.IGNORECASE),
    re.compile(r"within \d+ years?", re.IGNORECASE),
    re.compile(r"\bthis (?:study|sample|design|experiment)\b", re.IGNORECASE),
    re.compile(r"as of \d{4}", re.IGNORECASE),
    re.compile(r"\bcurrently\b", re.IGNORECASE),
    re.compile(r"over the (?:medium|long)[- ]term", re.IGNORECASE),
    re.compile(r"단기적(으로|인)"),
    re.compile(r"이\s*지표(에서|로)"),
    re.compile(r"\d+년\s*(내|이내)"),
    re.compile(r"(이|그|해당)\s*(연구|설계|표본|실험)"),
    re.compile(r"(보고된|한정된|특정)\s*표본"),
    re.compile(r"\d{4}년\s*현재"),
    re.compile(r"현재\s*기준"),
    re.compile(r"중장기"),
]
# Hegelian dialectic A/B/C position label (D1/D5). The letter is captured in `p`
# when it follows `Position ` (English `**Position A**`, per contradiction.md) or
# in `b` when it leads (`**C — Mediation**`, Korean `**A 입장**`). Single SoT:
# the encyclopedia-writing skill owns the label grammar (was a byte-identical
# second copy here); load it from the sibling skill so the copies cannot diverge.
_enc_spec = _ilu.spec_from_file_location(
    "enc_checks_jrn", Path(__file__).parent.parent / "encyclopedia-writing" / "checks.py"
)
_enc_checks = _ilu.module_from_spec(_enc_spec)
_enc_spec.loader.exec_module(_enc_checks)
DIALECTIC_LABEL_RE = _enc_checks.DIALECTIC_LABEL_RE
C_LABEL_BROAD_RE = re.compile(r"\*\*(?:Position\s+)?C\b[^*]*\*\*")  # language-agnostic (any **C …** / **Position C …** label)
# C-position meta-critique keywords (D6). English-native literals first; the Korean
# forms fire under WIKI_LANG=ko.
C_META_KEYWORDS = [
    "internal contradiction", "meta-critique", "meta-criticism", "self-serving",
    "interest bias", "both sides at once", "both camps", "fully neutral observer",
    "내부 모순", "메타 비판", "메타 비평", "셀프 서빙",
    "이해관계 편향", "양측 동시", "양쪽 모두", "완전 중립 관찰자",
    "모두 self", "둘 다 self",
]


def _count_words(text: str) -> int:
    """Whitespace-delimited word count (D5). Verbatim from contradiction.py."""
    return len([t for t in text.split() if t.strip()])


def _dialectic_paragraph_words(conflict_section: str) -> dict:
    """Per-paragraph A/B/C word counts in `## Opposing Positions`. Verbatim from
    contradiction.py."""
    out = {"A": 0, "B": 0, "C": 0}
    label_iter = list(DIALECTIC_LABEL_RE.finditer(conflict_section))
    for i, match in enumerate(label_iter):
        label = match.group("p") or match.group("b")
        start = match.end()
        end = label_iter[i + 1].start() if i + 1 < len(label_iter) else len(conflict_section)
        body = conflict_section[start:end]
        if out[label] == 0:
            out[label] = _count_words(body)
    return out


def evaluate_contradiction_dialectic(body: str, *, conflict_section: str) -> dict:
    """Measure contradiction theme jrn.* (T4 Toulmin qualifier·D1·D5·D6 Hegelian
    dialectic). conflict_section is orchestrator-injected. The returned dict is
    byte-identical to the corresponding _rubric_metrics keys (verbatim port)."""
    # T4 — qualifier tokens across the body
    qualifiers = sum(len(p.findall(body)) for p in QUALIFIER_PATTERNS)

    # D1 — number of distinct dialectic label kinds
    labels = len({
        m.group("p") or m.group("b") for m in DIALECTIC_LABEL_RE.finditer(conflict_section)
    })

    # D5 — A/B/C paragraph word counts
    paragraph_words = _dialectic_paragraph_words(conflict_section)
    a_w, b_w, c_w = paragraph_words["A"], paragraph_words["B"], paragraph_words["C"]

    # D6 — C-stance meta-critique keywords
    c_meta_hits: list = []
    c_matches = list(C_LABEL_BROAD_RE.finditer(conflict_section))
    if c_matches:
        c_start = c_matches[0].start()
        remainder = conflict_section[c_matches[0].end():]
        next_bullet = re.search(r"\n\s*-\s+", remainder)
        c_end = (
            c_matches[0].end() + next_bullet.start()
            if next_bullet else len(conflict_section)
        )
        c_region = conflict_section[c_start:c_end]
        for kw in C_META_KEYWORDS:
            if kw in c_region:
                c_meta_hits.append(kw)
    c_meta_count = len(c_meta_hits)

    return {
        "T4_qualifiers": qualifiers,
        "D1_labels": labels,
        "D5_words": {"A": a_w, "B": b_w, "C": c_w},
        "D6_c_meta_count": c_meta_count,
        "D6_c_meta_hits": c_meta_hits,
    }


def evaluate_contradiction_aggregate(*, insights_section: str) -> dict:
    """Measure contradiction aggregate jrn.* (T4 — `## Implications` qualifier).
    insights_section is orchestrator-injected. Ported verbatim from contradiction.py."""
    t4_qualifiers = sum(len(p.findall(insights_section)) for p in QUALIFIER_PATTERNS)
    return {"t4_qualifiers": t4_qualifiers}


def evaluate_overview_aggregate(*, all_links: list, cluster_slugs: set) -> dict:
    """Measure overview L2-4 D3 (cross-cluster reference balance — due impartiality).
    all_links·cluster_slugs are orchestrator-injected. Ported verbatim from
    overview.py. (Counts slug references — language-agnostic.)"""
    cluster_ref_counts: dict = {}
    for target in all_links:
        stem = target.strip().split("/")[-1].split("#", 1)[0]
        if stem in cluster_slugs:
            cluster_ref_counts[stem] = cluster_ref_counts.get(stem, 0) + 1
    if len(cluster_ref_counts) >= 2:
        max_refs = max(cluster_ref_counts.values())
        min_refs = min(cluster_ref_counts.values())
        d3_ratio = max_refs / min_refs if min_refs > 0 else float("inf")
    else:
        max_refs = sum(cluster_ref_counts.values())
        min_refs = max_refs if cluster_ref_counts else 0
        d3_ratio = 1.0 if cluster_ref_counts else 0.0
    return {"max_refs": max_refs, "min_refs": min_refs, "d3_ratio": d3_ratio}

{
  "skill": "journalism-writing",
  "_note": "Journalism/argumentation craft criteria, single SoT. The measurement function is given by each `algorithm` field — contradiction dialectic (qualifier·thesis-antithesis·c-section-size·c-stance-naming) uses `evaluate_contradiction_dialectic`; overview-aggregate reference balance (due-impartiality) uses `evaluate_overview_aggregate`. judge=M (narrative lead + Toulmin Claim-Warrant·Rebuttal·Hegel synthesis monitoring) keeps only definition + pass_condition and is reviewed qualitatively by desk. Authoring/review prose (with examples) is in SKILL.md. Shared parsing (conflict_section etc.) is orchestrator-injected. Any Korean literals are the wiki's actual section headers and matched tokens.",
  "criteria": {
    "jrn.lede": {
      "name": "Lede concreteness", "dimension": "Narrative lead", "judge": "M",
      "pass_condition": "The lede leads with the concrete conclusion via specific numbers and proper nouns (so-what upfront) rather than an abstract summary, compressed into 2–4 sentences.",
      "legacy": {"overview-cluster": "J1", "overview-aggregate": "J1"},
      "source": "Inverted Pyramid — Nielsen Norman Group", "source_url": "https://www.nngroup.com/articles/inverted-pyramid/"
    },
    "jrn.nutgraf": {
      "name": "Nut graph 4W1H", "dimension": "Narrative lead", "judge": "M",
      "pass_condition": "A core paragraph after the lede states why the story matters with 4W1H (scope·time·who·why).",
      "legacy": {"overview-cluster": "J2", "overview-aggregate": "J2"},
      "source": "Nut graph — Nieman Storyboard", "source_url": "https://niemanstoryboard.org/2021/10/26/nut-grafs-seven-steps-to-score-a-winning-story-structure/"
    },
    "jrn.kicker": {
      "name": "Kicker forward-looking", "dimension": "Narrative lead", "judge": "M",
      "pass_condition": "The intro closes with a forward-looking sentence declaring the tension/direction to track.",
      "legacy": {"overview-cluster": "J3"},
      "source": "Nut graph — Nieman Storyboard", "source_url": "https://niemanstoryboard.org/2021/10/26/nut-grafs-seven-steps-to-score-a-winning-story-structure/"
    },
    "jrn.page": {
      "name": "PAGE framing", "dimension": "Narrative lead", "judge": "M",
      "pass_condition": "Each tension axis is framed with at least 2 of the 4 PAGE elements (Problem·Analyze cause·Gauge responsibility·Examine solutions).",
      "legacy": {"overview-cluster": "J4"},
      "source": "The Power of News Frames (PAGE model) — Project Censored", "source_url": "https://www.projectcensored.org/the-power-of-news-frames/"
    },
    "jrn.explainer": {
      "name": "Explainer orientation", "dimension": "Narrative lead", "judge": "M",
      "pass_condition": "Body units are composed as explanation answering How/Why, not a bare list of facts.",
      "legacy": {"overview-cluster": "J5", "overview-aggregate": "J5"},
      "source": "Explanatory journalism — Wikipedia", "source_url": "https://en.wikipedia.org/wiki/Explanatory_journalism"
    },
    "jrn.inverted-pyramid": {
      "name": "Inverted pyramid", "dimension": "Narrative lead", "judge": "M",
      "pass_condition": "Lists/sections place the most important metric first (descending importance).",
      "legacy": {"overview-cluster": "J6", "overview-aggregate": "J6"},
      "source": "Inverted Pyramid — Nielsen Norman Group", "source_url": "https://www.nngroup.com/articles/inverted-pyramid/"
    },
    "jrn.due-impartiality": {
      "name": "Due impartiality (reference balance)", "dimension": "Fairness", "judge": "A",
      "algorithm": "evaluate_overview_aggregate", "comparator": "<=", "default_threshold": 3.0,
      "legacy": {"overview-aggregate": "D3"},
      "source": "Rethinking balance and impartiality in journalism — PMC (BBC)", "source_url": "https://pmc.ncbi.nlm.nih.gov/articles/PMC5732589/",
      "note": "In an aggregated piece, the max/min sub-unit reference ratio stays ≤ threshold so references do not over-skew to one side (BBC due impartiality). Measured by the evaluate_overview_aggregate bundle. A hub cluster may legitimately exceed this, so it is advisory (human review)."
    },
    "jrn.toulmin-claim": {
      "name": "Claim-Warrant", "dimension": "Toulmin", "judge": "M",
      "pass_condition": "Each side (A·B·optional C) pairs its claim with supporting grounds/data (≥1); no side asserts a claim with no grounds.",
      "legacy": {"contradiction-theme": "T1", "contradiction-aggregate": "T1"},
      "source": "Toulmin Argument — Purdue OWL", "source_url": "https://owl.purdue.edu/owl/general_writing/academic_writing/historical_perspectives_on_argumentation/toulmin_argument.html"
    },
    "jrn.rebuttal": {
      "name": "Rebuttal acknowledgment", "dimension": "Toulmin", "judge": "M",
      "pass_condition": "For each side (A·B), concede ≥1 real weakness grounded in one of (i) a limit the side itself admits, (ii) an internal contradiction in its logic, (iii) an evidence design limit (sample/timing/method). Re-citing the opposing side's evidence is NOT a rebuttal (it repeats the clash). No side left perfectly defended.",
      "legacy": {"contradiction-theme": "T3"},
      "source": "Toulmin Argument — Purdue OWL", "source_url": "https://owl.purdue.edu/owl/general_writing/academic_writing/historical_perspectives_on_argumentation/toulmin_argument.html"
    },
    "jrn.qualifier": {
      "name": "Qualifier present", "dimension": "Toulmin", "judge": "A",
      "algorithm": "evaluate_contradiction_dialectic", "comparator": ">=", "default_threshold": 1,
      "legacy": {"contradiction-theme": "T4", "contradiction-aggregate": "T4"},
      "source": "Toulmin Argument — Purdue OWL", "source_url": "https://owl.purdue.edu/owl/general_writing/academic_writing/historical_perspectives_on_argumentation/toulmin_argument.html",
      "note": "≥1 scope qualifier ('in the short term'·'on this metric'·'within N years', etc.) in the body. Every issue holds only conditionally (Toulmin Qualifier). For aggregate, limited to the Implications section. NOTE QUALIFIER_PATTERNS includes English-native scope qualifiers ('in the short term'·'currently'·'as of YYYY', etc.); the Korean phrasings fire under WIKI_LANG=ko."
    },
    "jrn.thesis-antithesis": {
      "name": "Thesis-Antithesis clarity", "dimension": "Dialectic", "judge": "A",
      "algorithm": "evaluate_contradiction_dialectic", "comparator": ">=", "default_threshold": 2,
      "legacy": {"contradiction-theme": "D1"},
      "source": "Hegel's Dialectics — Stanford Encyclopedia of Philosophy", "source_url": "https://plato.stanford.edu/entries/hegel-dialectics/",
      "note": "## Opposing Positions marks thesis/antithesis with **Position A**/**Position B** bold labels (≥2 label kinds). NOTE DIALECTIC_LABEL_RE matches the English '**Position A**' labels; the Korean subtitle forms (입장/중재) fire under WIKI_LANG=ko."
    },
    "jrn.c-section-size": {
      "name": "C-section size limit", "dimension": "Dialectic", "judge": "A",
      "algorithm": "evaluate_contradiction_dialectic", "comparator": "advisory", "default_threshold": null,
      "legacy": {"contradiction-theme": "D5"},
      "source": "Hegel's Dialectics — Stanford Encyclopedia of Philosophy", "source_url": "https://plato.stanford.edu/entries/hegel-dialectics/",
      "note": "The C (mediating) paragraph word count ≤ max(A, B) (so C is not mistaken for the main clash). A/B/C word counts measured."
    },
    "jrn.c-stance-naming": {
      "name": "C-stance naming rule", "dimension": "Dialectic", "judge": "A",
      "algorithm": "evaluate_contradiction_dialectic", "comparator": "==", "default_threshold": 0,
      "legacy": {"contradiction-theme": "D6"},
      "source": "Hegel's Dialectics — Stanford Encyclopedia of Philosophy", "source_url": "https://plato.stanford.edu/entries/hegel-dialectics/",
      "note": "The C label is allowed only when synthesis/mediating. If meta-critique keywords ('internal contradiction'·'both sides at once', etc.) appear, move the content to the Derived Tension section (0 violations). NOTE C_META_KEYWORDS includes English-native keywords ('internal contradiction'·'both sides at once', etc.); the Korean forms fire under WIKI_LANG=ko."
    },
    "jrn.monitoring-balance": {
      "name": "Synthesis / monitoring balance", "dimension": "Dialectic", "judge": "M",
      "pass_condition": "The synthesis (Interpretive Direction) includes a monitoring point for each side's (A·B·optional C) winning scenario (≥1 each). Skew to one side is FAIL (due impartiality) — place them symmetrically so no editorial verdict is hidden beneath hedged wording.",
      "legacy": {"contradiction-theme": "D2"},
      "source": "Hegel's Dialectics — Stanford Encyclopedia of Philosophy", "source_url": "https://plato.stanford.edu/entries/hegel-dialectics/"
    }
  }
}

---
name: journalism-writing
description: Journalism and argumentation writing craft — inverted pyramid, lede, nut graph, kicker, explainer framing, PAGE frames, Toulmin argument (claim/rebuttal/qualifier), Hegelian dialectic, BBC due impartiality. Use when writing or reviewing news/explainer pieces, landscape overviews, or issue analyses that fairly juxtapose opposing views, or when a strong lede, sound argument structure, or balanced conclusion is needed.
---

# journalism-writing

Writing craft drawn from news/explanatory journalism and argumentation traditions — narrative lead (Lede→Nut graph→Kicker), dialectical structure (thesis·antithesis·synthesis), argument quality (Toulmin), and fairness (BBC due impartiality). `criteria.json` is the SoT for each criterion's definition, comparator, and source. The shared parsing and wiki-global state that the deterministic checks (judge=A) rely on are injected by the orchestrator (the skill is content-type-agnostic). Examples are illustrative of the target English prose.

## Dialectic structure (jrn.thesis-antithesis · jrn.c-section-size · jrn.c-stance-naming · jrn.monitoring-balance)

Develop an issue as Hegelian thesis → antithesis → synthesis. State thesis and antithesis with explicit **Position A / Position B** bold labels (ko rendering: **A 입장 / B 입장**); add a **C — Mediation** label (ko: **C 중재**) only when a genuine convergence exists. The C paragraph must not run longer than the longer of A and B, so the convergence is not mistaken for the main clash. If C is not a synthesis but a meta-critique (weakening both sides at once, flagging interest bias), move it out of the dialectic frame — a meta-critique in the C slot breaks the three-part structure.

Synthesis does not pick a winner. In Hegel's terms it *sublates* — cancels and preserves — identifying what each side correctly grasps. Concretely, place each side's **monitoring point** (what one would observe if that side were right) symmetrically (jrn.monitoring-balance); a monitor skewed to one side hides an editorial verdict under hedged wording (combine with BBC due impartiality). e.g. ✅ "If tighter regulation is right, we would observe reduced consumer harm; if looser regulation is right, increased new entry" (winning conditions symmetric on both sides) / ❌ "Regulation blocks innovation, so abolishing it is right" (one-sided verdict).

## Argument quality (jrn.toulmin-claim · jrn.rebuttal · jrn.qualifier)

Check each side's support structure with the Toulmin model (claim · grounds/data · warrant · qualifier · rebuttal · backing).

- **Claim-Warrant** (jrn.toulmin-claim) — every side pairs its claim with the grounds (data) that support it; no side asserts a claim with no grounds. e.g. ✅ "Regulation slows innovation — the grounds: new licensing waits average 18 months" (claim + grounds) / ❌ "Regulation slows innovation" (ungrounded assertion)
- **Rebuttal acknowledgment** (jrn.rebuttal) — concede a real weakness for each side, grounded in one of: (i) a limit the side itself admits, (ii) an internal contradiction in its logic, (iii) a design limit of its evidence (sample/timing/method). Re-citing the opposing side's evidence is NOT a rebuttal — it merely repeats the clash and loses the Toulmin value of a flaw seen from within the side. No side may be left perfectly defended. e.g. ✅ "However, this measurement is a first-generation adoption sample, so whether the same result holds at maturity is untested" (a design limit of one's own side) / ❌ "The opposing side also has many failure cases" (re-citing the opponent's evidence — not a rebuttal)
- **Qualifier** (jrn.qualifier) — every claim holds only conditionally; include at least one scope qualifier ("in the short term"·"on this metric"·"within 5 years"·"under this study design") so the claim is not over-generalized.

## Fairness (jrn.due-impartiality)

When aggregating many topics/sides into one piece, keep length and references from skewing to one side — BBC due impartiality is proportionate to weight, not a mechanical 50:50, and privileges no side. The deterministic check signals via a max/min reference-ratio ceiling (default 3.0, see criteria.json), but a hub that is intrinsically more referenced can be normal, so human review accompanies it.

## Narrative lead (jrn.lede · jrn.nutgraf · jrn.kicker · jrn.page · jrn.explainer · jrn.inverted-pyramid)

News/explanatory journalism front-loads the point and descends into detail — in the inverted pyramid, "the most important information (or what might even be considered the conclusion) is presented first." These resist deterministic measurement (judge=M, qualitative review); the source techniques shared by author and reviewer:

- **Lede** (jrn.lede) — open with the concrete conclusion (specific numbers/proper nouns), not an abstract summary ("so-what upfront"); compress into 2–4 sentences rather than one overloaded sentence. e.g. ✅ "Flexible work raised team productivity 30% — the result of a six-month study of work arrangements" / ❌ "Many factors affect productivity, and the analysis found scheduling mattered" (abstract intro)
- **Nut graph** (jrn.nutgraf) — the paragraph after the lede that states why the story matters, with 4W1H (scope·time·who·why). e.g. ✅ "This decision splits the field of three camps that have competed for three years — who rises and who is eliminated is decided here" (why it matters) / ❌ "The event was held yesterday with many participants" (facts only, no so-what)
- **Kicker** (jrn.kicker) — close the intro with a forward-looking sentence that signals the tension to track. e.g. ✅ "Whether next quarter's metrics will reverse this trend is the question" / ❌ "Various things followed afterward" (no direction)
- **PAGE framing** (jrn.page) — frame an issue across Problem → Analyze cause → Gauge responsibility → Examine solutions, covering at least 2 of the 4 per axis to avoid one-dimensional reporting. e.g. ✅ frame a cost increase along two axes, "market-structure cause (Analyze) + policy-intervention responsibility (Gauge responsibility)" / ❌ "costs rose" — a single-angle account
- **Explainer** (jrn.explainer) — compose body units that answer How/Why (greater context to understand a complicated topic), not a bare list of facts (Vox-style). e.g. ✅ "Why this bill was needed now and how it affects ordinary users" (How·Why) / ❌ "Congress passed the bill 52 votes" (fact listing)
- **Inverted pyramid** (jrn.inverted-pyramid) — order lists/sections by descending importance, most important metric first. e.g. ✅ put "share up 30%" at the front, with background·methodology after / ❌ start with background·methodology and put the conclusion at the very end

How each technique maps to a specific page/section/paragraph is defined by the `.claude/layers/` content-type guides.

## Beat reporting framing (judge=M — beat reporting · stakeholder map)

Follow beat-reporting practice: an overview is not a one-off article but the product of sustained, cumulative coverage of a field. Present the actors not as a flat list but grouped by role (principal · partner · regulator — a stakeholder map). Resists deterministic measurement; judged qualitatively.

## Sources

Each URL points to the relevant page as of the last verification.

- [Inverted Pyramid — Nielsen Norman Group](https://www.nngroup.com/articles/inverted-pyramid/) — inverted pyramid·readability
- [Nut graph — Wikipedia](https://en.wikipedia.org/wiki/Nut_graph) · [Nailing the Nut Graf — The Open Notebook](https://www.theopennotebook.com/2014/04/29/nailing-the-nut-graf/) · [Nieman Storyboard](https://niemanstoryboard.org/2021/10/26/nut-grafs-seven-steps-to-score-a-winning-story-structure/) — Lede→Nut graph→Kicker
- [The Power of News Frames (PAGE model) — Project Censored](https://www.projectcensored.org/the-power-of-news-frames/) — four-stage framing
- [Explanatory journalism — Wikipedia](https://en.wikipedia.org/wiki/Explanatory_journalism) — explainer (Vox)
- [Beat reporting — Wikipedia](https://en.wikipedia.org/wiki/Beat_reporting) — beat reporting·stakeholder map
- [Toulmin Argument — Purdue OWL](https://owl.purdue.edu/owl/general_writing/academic_writing/historical_perspectives_on_argumentation/toulmin_argument.html) — Claim·Data·Warrant·Rebuttal·Qualifier
- [Hegel's Dialectics — Stanford Encyclopedia of Philosophy](https://plato.stanford.edu/entries/hegel-dialectics/) — thesis·antithesis·synthesis three-part structure
- [Rethinking balance and impartiality in journalism — PMC (BBC)](https://pmc.ncbi.nlm.nih.gov/articles/PMC5732589/) — due impartiality