# consulting-writing

Adopt this skill: https://proskills.md/skills/other/alfadur7-llm-wiki-newsroom-claude-skills-consulting-writing

Page: https://proskills.md/skills/other/alfadur7-llm-wiki-newsroom-claude-skills-consulting-writing
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: .claude/skills/consulting-writing/SKILL.md
size: 4466
sha: 981be531a1ce86680ed3236f63444ae3c36e41ce
upstream: https://github.com/alfadur7/llm-wiki-newsroom/blob/main/.claude/skills/consulting-writing/SKILL.md

```text
---
name: consulting-writing
description: Management-consulting writing craft — McKinsey SCR (Situation·Complication·Resolution), Minto Pyramid/MECE, BCG bold-bullet executive summary, so-what upfront, numeric precision, Forrester Landscape. Use when writing or reviewing an executive summary for decision-makers or a roll-up/landscape overview, or when a conclusion-first compressed structure, MECE completeness, or bold-bullet summary is needed.
---

# consulting-writing

Writing craft drawn from management-consulting deliverables — the executive-summary / pyramid structure that compresses a complex domain for decision-makers, and the MECE completeness of a roll-up. `criteria.json` is the SoT for each criterion's definition, comparator, and source; shared parsing for the deterministic checks is orchestrator-injected (the skill is content-type-agnostic). Examples are illustrative of the target English prose.

## MECE completeness (con.mece-axes · con.mece-clusters)

A roll-up document must cover its subitems with no overlap and no gaps — the MECE principle separates a set of items into subsets that are "mutually exclusive (ME) and collectively exhaustive (CE)." Group many items under 2–4 top axes, place every item under at least one axis, and put anything that fits nowhere into an explicit residual (`기타` / "other") axis. Every subunit (cluster, theme, …) must appear in the roll-up (collectively exhaustive — no subunit dropped).

## Executive Summary structure (con.scr · con.so-what · con.bold-bullet · con.numeric-precision)

The intro craft that compresses a complex domain for a decision-maker. Resists deterministic measurement (judge=M, qualitative review); the source techniques shared by author and reviewer:

- **SCR** (con.scr) — develop the intro as Situation → Complication → Resolution (McKinsey). e.g. ✅ "Market share fell 8% year over year (Situation). A competitor entered at a 15% lower price (Complication). We respond by repositioning as premium (Resolution)." / ❌ "The market environment is difficult and improvement is needed" (Situation·Complication·Resolution undifferentiated)
- **So-what upfront** (con.so-what) — lead with the conclusion (the key implication), not a long description or preamble. e.g. ✅ "We can cut indirect costs by ₩2B per year — labor, supply waste, and process inefficiency are the drivers" (conclusion first) / ❌ "We analyzed three factors affecting profitability…" (description first)
- **Bold-bullet** (con.bold-bullet) — build metric runs as a bold key-claim heading + supporting bullets, so the scannable takeaway is the bold line (BCG executive-summary standard: lead with the "so what", evidence below). e.g. ✅ "**Market consolidation drives customer acquisition cost up 34% per year** — Q2 three-way merger shrinks the vendor pool / pressure on the procurement team's volume discounts" (bold conclusion + grounds) / ❌ "The market is changing / competitors are consolidating / customers want better prices" (flat bullets, no conclusion)
- **Numeric precision** (con.numeric-precision) — support claims with concrete numbers (amount·date·%·proper noun) instead of vague quantifiers. e.g. ✅ "Revenue grows 12% through Q3 2026, adding ₩4.5B" / ❌ "Revenue will rise significantly going forward" (abstract quantifier)
- **Numeric density** (con.numeric-density) — do not overpack a paragraph with numbers; isolate key numbers in bold-bullets so they are not buried (deterministic measurement — per-paragraph number-token ceiling, threshold injected by manifest).

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

## Sources

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

- [How to Write an Executive Summary Like McKinsey — Slideworks](https://slideworks.io/resources/how-to-write-executive-summary) — SCR (Situation-Complication-Resolution)
- [Understanding BCG's Approach to Executive Summaries — Insight7](https://insight7.io/understanding-bcgs-approach-to-executive-summaries/) — Bold-bullet·So-what upfront
- [MECE principle — Wikipedia](https://en.wikipedia.org/wiki/MECE_principle) — Barbara Minto·McKinsey Pyramid Principle (Collectively Exhaustive)
- [The FIGs: Forrester, Gartner, IDC — Starsight](https://www.starsight.biz/2023/04/20/the-figs-who-are-the-biggest-analyst-firms/) — Forrester Landscape report structure
```

## File: .claude/skills/consulting-writing/checks.py
size: 4815
sha: ede259a2a7529134f5089df59f20bc03cc828bae
upstream: https://github.com/alfadur7/llm-wiki-newsroom/blob/main/.claude/skills/consulting-writing/checks.py

```text
"""consulting-writing craft skill — deterministic checks.

Craft drawn from the management-consulting deliverable tradition (McKinsey SCR·
Minto Pyramid/MECE·BCG bold-bullet·"So what upfront"·Forrester Landscape). It owns
the MECE (Collectively Exhaustive) measurements of an aggregate roll-up —
overview L2-4 cluster completeness and contradiction-aggregate tension-axis
grouping. Many criteria (C1 SCR·C2 bold-bullet·C3 So-what·S2 numeric precision,
etc.) are judge=M (qualitative), so only the SKILL.md /
criteria.json definitions live here and desk reviews them.

content-type-agnostic: shared parsing (analysis_section·content·cluster_slugs) is
orchestrator-injected. The measurement logic was ported verbatim from lint
(_check_*_md).
"""

from __future__ import annotations

import re

# MECE measurement regexes (verbatim from lint) — language-agnostic structure
# (### headings, ## N. [[slug]] section markers).
AXIS_SUBSECTION_RE = re.compile(r"^###\s+(.+?)\s*$", re.MULTILINE)
CLUSTER_SECTION_RE = re.compile(
    r"^##\s+\d+\.\s+\[\[([a-z][a-z0-9\-]+)(?:\|[^\]]*)?\]\]", re.MULTILINE
)
AXES_MIN = 2
AXES_MAX = 4

# ── con.numeric-density (BCG number isolation) — ported verbatim from overview.py ──
# When one paragraph is overpacked with number tokens, the key numbers get buried
# (BCG: isolate them in bold-bullets). Date fragments and wikilink targets are
# editorially meaningless numbers, so they are masked first. Threshold is
# manifest-injected.
_DENSITY_DATE_YMD_RE = re.compile(r"\b\d{4}(?:[-./]\d{1,2}(?:[-./]\d{1,2})?)?\b")
# (dormant: matched Korean date suffixes 년/월/일; an English wiki uses numeric or
#  ISO dates, already covered by _DENSITY_DATE_YMD_RE above. See FLAG in summary.)
_DENSITY_DATE_KO_RE = re.compile(r"\d{4}\s*년(?:\s*\d{1,2}\s*월(?:\s*\d{1,2}\s*일)?)?")
# Number+unit token for paragraph figure density. English-native units/magnitudes
# first; the Korean counters fire under WIKI_LANG=ko.
_DENSITY_NUM_UNIT_RE = re.compile(
    r"\d+(?:[,.]\d+)*\s*(?:%|percent|billion|million|trillion|"
    r"GB|TB|PB|GW|MW|km|kg|ppm|hours?|cases?|people|users|points?|"
    r"조|억|천만|백만|만|건|대|명|장|배|개월|개|호|층|년|번째|주|시간|분)"
)

def count_density_violations(content: str, *, max_per_para: int = 5) -> list:
    """con.numeric-density — list of (paragraph index, count) for paragraphs whose
    number-token count > max_per_para.

    content is the EDITOR region extracted by the orchestrator. After masking dates
    and wikilinks, split into paragraphs on blank lines. The threshold VALUE is
    manifest-injected (content-type-agnostic)."""
    clean = _DENSITY_DATE_YMD_RE.sub(" ", content)
    clean = _DENSITY_DATE_KO_RE.sub(" ", clean)
    clean = re.sub(r"\[\[[^\]]+\]\]", " ", clean)
    paras = re.split(r"\n\s*\n", clean)
    violations = []
    for i, p in enumerate(paras):
        if not p.strip():
            continue
        count = len(_DENSITY_NUM_UNIT_RE.findall(p))
        if count > max_per_para:
            violations.append((i, count))
    return violations

def eval_contradiction_aggregate_mece(analysis_section: str) -> dict:
    """contradiction aggregate D1 — count of `### <axis>` subsections under
    `## Per-Theme Deep Analysis` (`### 기타`/other is excluded as the MECE
    residual). axes in the 2–4 range. axes_named is also returned because N7 (enc)
    reuses it. Ported verbatim from contradiction.py.

    (The residual axis is excluded from the count: English `Other` or, under
    WIKI_LANG=ko, `기타`.)"""
    axis_matches = AXIS_SUBSECTION_RE.findall(analysis_section)
    axes_named = [a for a in axis_matches if a.strip().lower() not in ("other", "기타")]
    d1_axes = len(axes_named)
    return {
        "d1_axes": d1_axes,
        "axes_named": axes_named,
        "d1_ok": AXES_MIN <= d1_axes <= AXES_MAX,
        "axes_min": AXES_MIN,
        "axes_max": AXES_MAX,
    }

def eval_overview_aggregate_mece(content: str, *, cluster_slugs: set) -> dict:
    """overview L2-4 D1 — every cluster appears as a `## N. [[slug|alias]]` section
    (MECE Collectively Exhaustive). The section matches are returned with their
    (slug, end-pos) info because D2 (enc drill-down) reuses them. Ported verbatim
    from overview.py."""
    section_spans = [
        (m.group(1), m.end()) for m in CLUSTER_SECTION_RE.finditer(content)
    ]
    sections_found = {slug for slug, _ in section_spans}
    d1_count = len(sections_found & cluster_slugs)
    d1_total = len(cluster_slugs)
    return {
        "d1_count": d1_count,
        "d1_total": d1_total,
        "d1_ok": d1_count == d1_total,
        "d1_missing": sorted(cluster_slugs - sections_found),
        "section_spans": section_spans,
        "section_count": len(section_spans),
    }
```

## File: .claude/skills/consulting-writing/criteria.json
size: 4288
sha: 3f236266f8cdfcefd728a77471ae44ab1acbac20
upstream: https://github.com/alfadur7/llm-wiki-newsroom/blob/main/.claude/skills/consulting-writing/criteria.json

```text
{
  "skill": "consulting-writing",
  "_note": "Management-consulting craft criteria. The measurement function is given by each `algorithm` field — MECE completeness (mece-axes·mece-clusters) uses `eval_*_aggregate_mece`; numeric density (numeric-density) uses `count_density_violations`. judge=M (SCR·bold-bullet·so-what·numeric precision — executive-summary narrative) keeps only definition + pass_condition and is reviewed qualitatively by desk. Authoring/review prose (with examples) is in SKILL.md. Shared parsing is orchestrator-injected. Any Korean literals are the wiki's actual section headers.",
  "criteria": {
    "con.scr": {
      "name": "SCR structure", "dimension": "Executive Summary", "judge": "M",
      "pass_condition": "The intro shows all three of Situation·Complication·Resolution.",
      "legacy": {"overview-cluster": "C1", "overview-aggregate": "C1"},
      "source": "How to Write an Executive Summary Like McKinsey — Slideworks", "source_url": "https://slideworks.io/resources/how-to-write-executive-summary"
    },
    "con.so-what": {
      "name": "So-what upfront", "dimension": "Executive Summary", "judge": "M",
      "pass_condition": "The intro leads with the conclusion (key implication) rather than dragging through description/preamble.",
      "legacy": {"overview-cluster": "C3", "overview-aggregate": "C3"},
      "source": "How to Write an Executive Summary Like McKinsey — Slideworks", "source_url": "https://slideworks.io/resources/how-to-write-executive-summary"
    },
    "con.bold-bullet": {
      "name": "Bold-bullet pattern", "dimension": "Executive Summary", "judge": "M",
      "pass_condition": "Metric runs are consistently built as a **bold key-claim heading** + supporting bullets.",
      "legacy": {"overview-cluster": "C2", "overview-aggregate": "C2"},
      "source": "Understanding BCG's Approach to Executive Summaries — Insight7", "source_url": "https://insight7.io/understanding-bcgs-approach-to-executive-summaries/"
    },
    "con.numeric-precision": {
      "name": "Numeric precision", "dimension": "Executive Summary", "judge": "M",
      "pass_condition": "Concrete numbers (amount·date·%·proper noun) support claims instead of vague quantifiers (e.g. 'a large amount'·'trillions').",
      "legacy": {"overview-cluster": "S2", "overview-aggregate": "S2"},
      "source": "How to Write an Executive Summary Like McKinsey — Slideworks", "source_url": "https://slideworks.io/resources/how-to-write-executive-summary"
    },
    "con.numeric-density": {
      "name": "Numeric density (BCG isolation)", "dimension": "Executive Summary", "judge": "A",
      "algorithm": "count_density_violations", "comparator": "<=", "default_threshold": 0,
      "legacy": {"overview-cluster": "R2", "overview-aggregate": "R2"},
      "source": "Understanding BCG's Approach to Executive Summaries — Insight7", "source_url": "https://insight7.io/understanding-bcgs-approach-to-executive-summaries/",
      "note": "Number of paragraphs whose number-token count > max_per_para is ≤ threshold (0). Key numbers isolated in bold-bullets. max_per_para·threshold injected by manifest."
    },
    "con.mece-axes": {
      "name": "Tension-axis grouping (MECE)", "dimension": "MECE", "judge": "A",
      "algorithm": "eval_contradiction_aggregate_mece", "comparator": "range", "default_threshold": [2, 4],
      "legacy": {"contradiction-aggregate": "D1"},
      "source": "MECE principle — Barbara Minto·McKinsey Pyramid", "source_url": "https://en.wikipedia.org/wiki/MECE_principle",
      "note": "2–4 ### <axis> subsections under ## Per-Theme Deep Analysis, every theme under ≥1 axis (the residual '기타'/other axis excluded). Collectively Exhaustive."
    },
    "con.mece-clusters": {
      "name": "Cluster-section completeness (MECE)", "dimension": "MECE", "judge": "A",
      "algorithm": "eval_overview_aggregate_mece", "comparator": "==", "default_threshold": "cluster_total",
      "legacy": {"overview-aggregate": "D1"},
      "source": "MECE principle — Barbara Minto·McKinsey Pyramid", "source_url": "https://en.wikipedia.org/wiki/MECE_principle",
      "note": "Every cluster in graph/_clusters.json appears as a ## N. [[slug|alias]] section (Collectively Exhaustive)."
    }
  }
}
```

## File: README.md
upstream: https://github.com/alfadur7/llm-wiki-newsroom/blob/main/README.md

````text
# LLM Wiki Newsroom

[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

**A multi-agent AI knowledge base run by a five-role "newsroom" — open-source, local-first, no vendor lock-in.** Drop articles, documents, and PDFs into the `raw/` folder, type a single command, and the newsroom — powered by an agent like Claude Code — reads them, extracts entities, concepts, and relationships, and organizes everything into a fully cross-referenced wiki, a structured and persistent alternative to RAG. Unlike most takes on the idea, the agent that *writes* a page is never the one that *reviews* it, and the authoring guidelines evolve themselves over time. Every new document you add also enriches the existing pages. This repo ships with a small example corpus — the debate over what "open source" means for AI — under `wiki/`, but the framework is domain-agnostic.

> Most knowledge tools leave the *finding* to you. This project **makes the AI read and understand** your collected documents first, then organizes them into a wiki — with cross-references between pages, automatic flagging of conflicting claims, and per-topic synthesis built in from the start, so later retrieval is fast.

> **See the output before installing** — the example corpus shipped in this repo is published as a browsable **[GitHub Wiki](https://github.com/alfadur7/llm-wiki-newsroom/wiki)** (no clone needed). It's a rendered static snapshot of the `wiki/` folder; the interactive graph below runs locally.

![The interactive knowledge graph browser — every page a node, every wikilink an edge, auto-grouped into color-coded clusters with relationship-typed links](docs/knowledge-graph.png)

<sub>The interactive knowledge graph (`graph/graph.html`) — every page a node, every wikilink an edge, color-coded by auto-detected cluster, with a live physics layout and filter/search built in. Shown here on a larger private deployment (~2,300 nodes) to convey how it scales; **this repo ships a deliberately small example corpus** you can browse the exact same way. (Interface shown in the optional Korean `WIKI_LANG=ko` mode.)</sub>

## The concept

This project is one question worked into a running system: **how far can you trust knowledge an AI wrote?** Two ideas organize everything below.

**1. The product is an [LLM Wiki](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f) — Andrej Karpathy's three-layer pattern.** The original documents you collect (Layer 1, `raw/`), the cross-linked wiki the agent maintains (Layer 2, `wiki/`), and the operating rules the agent follows (Layer 3, `CLAUDE.md` + `.claude/`) are kept strictly separate, so humans and AI don't trespass into each other's territory. As the operator you do exactly two things — feed Layer 1 and tune Layer 3; **only the agent writes Layer 2**. And ingesting one document doesn't just add a page: it refreshes the ~10–15 existing pages that mention the same entities and concepts, which is what makes the wiki compound instead of just piling up.

**2. The factory is a newsroom running four loops.** The wiki is produced by five roles modeled on a newspaper staff — and the agent that *writes* a page is never the one that *reviews* it:

| Role | What it does |
|---|---|
| **Reporter** | gathers material and drafts source pages + entity/concept stubs |
| **Columnist** | writes the deep cross-source analyses |
| **Copy Editor** | rule-based Python checks — not an LLM at all |
| **Desk** | re-reads finished drafts with fresh eyes; the only independent qualitative judgment in the system |
| **Editor-in-Chief** | routes work and gates publication — orchestration, not evaluation |

Four loops turn that division of labor into trust. The first three nest inside one another; only the fourth sits outside, feeding published pages back in:

```mermaid
%%{init: {"flowchart": {"wrappingWidth": 700}}}%%
flowchart BT
    subgraph meta["Meta loop — mistakes become new rules"]
        subgraph outer["Outer loop — two gates before publication"]
            inner["Inner loop — the writer self-checks while drafting"]
        end
    end
    %% the &nbsp; padding keeps this box as wide as the Meta loop box above
    reground["&nbsp;&nbsp;Reground loop — pages that go stale or inconsistent come back as input&nbsp;&nbsp;"]
    reground -.-> meta
    style meta fill:transparent,stroke:#58a6ff,stroke-width:2px
    style outer fill:transparent,stroke:#3fb950,stroke-width:2px
    style inner fill:transparent,stroke:#d29922,stroke-width:2px
    style reground fill:transparent,stroke:#bc8cff,stroke-width:2px,stroke-dasharray:4 4
```

| Loop | When it runs | What it does |
|---|---|---|
| **Inner** | while drafting | the writer self-checks against the same yardstick the review gates will use later, and hands off instead of grinding |
| **Outer** | at publication | two gates — deterministic lint (Copy Editor), then a six-lens qualitative review (Desk) — and both must pass |
| **Meta** | when mistakes recur | repeat failures become proposals to amend the authoring rules themselves — blind measurement where it applies, operator sign-off always |
| **Reground** | after publication | published pages that have gone stale or inconsistent come back around as factory input |

One piece of the machinery is deliberately *not* a loop. A loop is feedback — something exists, gets checked, gets corrected. Before any loop runs, a **GROUND Ladder** governs the input side: how much the writer reads before drafting, widening from the page's declared dependencies toward the whole corpus only on a named signal that the evidence so far is insufficient. The loops correct what came out; the ladder disciplines what goes in — every authoring cycle enters through it. (Details under [Key Features](#before-the-loops--the-ground-ladder).)

The first three loops mirror the "software factory" playbook for AI-assisted coding; the fourth exists because knowledge, unlike code, keeps decaying after you ship it. The full argument for this design is in the companion article: **[The Knowledge Factory](https://alfadur7.github.io/llm-wiki-newsroom/knowledge-factory/)**.

Everything else in this README — the commands, the tools, the feature list — hangs off this map.

## What makes this different

There are plenty of takes on Karpathy's LLM Wiki idea now. After reading the popular implementations, three things here are genuinely rare — and they are the bet:

- **Authoring guidelines that evolve themselves** (the meta loop) — something I haven't found in the other implementations. When the same review failure keeps recurring, the system drafts a fix to its *own writing rules*. The idea is borrowed from [Self-Harness](https://arxiv.org/abs/2606.09498) and [Microsoft SkillOpt](https://github.com/microsoft/SkillOpt). Where the fix touches prose an LLM judge scores, it has to clear a blind A/B against a regression set first; tool code, fact corrections and structural moves are verified deterministically instead, and I can waive the A/B by directing a change myself, with the reason recorded. So it isn't only the wiki that improves over time, but the rules that build it. *(Thirteen weeks of that ledger on a private instance: **107 amendments adopted, 72 rejected, 18 deferred.** Of the 107, 16 cite a measurement, 40 were adopted on a recorded waiver, and 51 are changes the A/B doesn't cover or that record no measurement. Over the same window, **44 of the 70 defect classes that ever got a fix came back afterwards, and five of them produced 451 of the 823 recurrences (55%)**; the rule amended most often has been rewritten 19 times and still fires. The loop is still experimental; I'm measuring whether it earns its keep rather than claiming it's solved.)*
- **A full newsroom, not just "an agent"** (the outer loop) — plenty of tools wrap one agent around your notes, and a few add a verifier. Here authoring and review sit in different hands, the review is held to an editorial rubric drawn from real craft (journ
````
