"""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),
    }

{
  "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)."
    }
  }
}

---
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