agentleFS
imran-sayed-proimran-sayed-pro/claude-skills/issue-tree/SKILL.md

issue-tree

Skill0 starsChanged 4 months agoMITView on GitHub

Break a complex, ambiguous problem into a structured, MECE issue tree the way a McKinsey consultant would — then turn the leaves into testable hypotheses and precise data requests. Use this skill whenever the user says "build an issue tree", "break down this problem", "why is X happening", "what's driving X", "root cause analysis", "structure this problem", "MECE breakdown", "help me diagnose", "make an issue tree for", or presents a messy business/analytics problem they need decomposed before analyzing. Use it to structure a problem into causes (diagnostic) or into options for a known cause (solution) — including diagnosing why a product, software, or AI metric changed (e.g. "why is our churn model underperforming", "why did activation drop"). NOT for choosing between already-defined options with known payoffs (use expected-value-calculator), NOT for scoring a startup or business idea (use opportunity-evaluator), NOT for stress-testing an already-structured plan with questions (use grill-me), and NOT for a forward-looking product/software/AI goal whose path is validated through experiments rather than analysis, or whenever the user names the Thoughtful Execution framework — use thoughtful-execution instead for those.

3 other projects use a version of this.

Adopted by

Most recently taken up by

  • Other versions3 projects use a version of this.

    Word for word · 0

    None found.

    Edited · 0

    None found.

    Wrote their own version · 3

    1. fzfclee/consulting-skills★ 6same name
    2. Nomanriaz786/claude-consulting-team★ 1same name
    3. CAPP-Financials/Consulting_Brain★ 0same name

    How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.

  • In this repository4 other files it gives its agents.

The file

We split this skill into the rules it gives an agent

11 rules. 0 are common, 11 are distinctive, and 0 are very specific to this project.

  • 0

    Common

    Most of the 3 edited versions we read keep these.

  • 11

    Distinctive

    This author's own choices. Worth a look.

  • 0

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    If the user's problem is already quantified, use their numbers and skip straight to the question block below.

    line 41
  2. Distinctive:

    Wait for the user's reply: before building the tree. (Step 0 still applies: never ask something the user already stated earlier in the …

    line 59
  3. Distinctive:

    Pet-theory guard: If the user asks for solutions to a problem whose cause is *not* yet established, flag it: building a solution tree on an …

    line 66
  4. Distinctive:

    When no clean identity exists (qualitative problems), decompose by process stages, stakeholder/segment, or lifecycle phase instead — pick …

    line 83
  5. Distinctive:

    Stopping rule: Stop splitting a branch when its leaf is a testable hypothesis — something you could confirm or kill with data, an …

    line 85
  6. Distinctive:

    Before prioritizing, audit the tree explicitly against these four checks — this is what separates a real issue tree from a bullet list, and …

    line 110
  7. Distinctive:

    If any check fails, revise the tree before moving on — the report should never present a tree that fails its own audit.

    line 119
  8. Distinctive:

    Fallback: markdown/ASCII in chat: If HTML cannot be produced or rendered in the current session (no file/artifact capability, or the user …

    line 174
  9. Distinctive:

    Keep branch labels short and parallel (all nouns, or all "X did Y" clauses) — parallelism makes overlaps visible.

    line 205
  10. Distinctive:

    Never fake exhaustiveness.

    line 206
  11. Distinctive:

    No HTML-rendering capability in the session: Use the markdown/ASCII fallback in Step 6 and say so explicitly — don't silently degrade …

    line 219

“Common” is measured: kept by at least 6 in 10 of the 3 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Issue Tree (McKinsey MECE Decomposition)

A structured method for breaking a large, fuzzy problem into a MECE tree of sub-problems, driving each branch down to a testable hypothesis, and converting those hypotheses into precise, bounded data requests. This is the "Business Understanding" blueprint you build before running analysis — so investigation is directed, not a fishing expedition.

The two core rules that govern every tree:

  • Mutually Exclusive — branches at the same level cannot overlap. No root cause is counted twice.
  • Collectively Exhaustive — branches at the same level cover 100% of the parent's problem space. Nothing is left out.

Step 1: Frame the Problem, Ask What Only the User Knows, and Pick the Tree Type

Restate the problem as one sharp, quantified question. Vague in, vague out.

  • Weak: "Our profitability is a problem."
  • Strong: "Why did our EBITDA margin fall 4 points in H2 2025?"

If the user's problem is already quantified, use their numbers and skip straight to the question block below. If not, state the sharpest version you can as a working framing — it gets confirmed or corrected by the questions anyway.

Ask what only the user knows. A tree built without the user's own facts is a plausible guess, not an analysis — the entire value of an issue tree is that it's grounded in what the client actually knows. Before building anything, generate 3–5 targeted questions specific to this problem, covering whichever of these apply:

  • Quantification — how much, since when, compared to what baseline?
  • What's already known or ruled out — any suspected cause, prior investigation, or dead end?
  • Constraints — budget, timeline, or values that should rule branches in or out?
  • Available data — what records, logs, or reports already exist that could later answer Step 5's requests?

Present them as one numbered list in a single message. End with an explicit escape hatch:

Answer what you can — or reply "proceed with assumptions" and I'll build a first-draft tree with every gap clearly flagged.

Wait for the user's reply before building the tree. (Step 0 still applies: never ask something the user already stated earlier in the conversation.)

Once you have their answer (full, partial, or "proceed with assumptions"), declare the tree type explicitly:

  • Diagnostic tree (the "Why") — the cause is unknown. Decompose the problem into its functional or mathematical drivers to find the root cause.
  • Solution tree (the "How") — the root cause is already known. Decompose the fix into mutually exclusive pathways.

Pet-theory guard: If the user asks for solutions to a problem whose cause is not yet established, flag it: building a solution tree on an undiagnosed problem smuggles in an unproven assumption. Recommend a diagnostic tree first — then proceed with whichever the user chooses.


Step 2: Build the Tree

Decompose the framed question into a MECE tree.

Structural rules:

  • 2–4 branches per level (5 is the hard ceiling). More than 5 means you are listing, not structuring — group them.
  • 3–4 levels deep, typically. Go deeper only on branches that need it.
  • Prefer an arithmetic or logical identity at Level 1 whenever one exists — identities are provably MECE:
    • Profit = Revenue − Cost
    • Revenue = Volume × Price (or # Customers × Revenue per Customer)
    • Cost = Fixed Cost + Variable Cost
    • Churn Rate = f(data-quality issues, model issues) for an ML problem
    • Total Time = Σ (time per process step)
  • When no clean identity exists (qualitative problems), decompose by process stages, stakeholder/segment, or lifecycle phase instead — pick one axis per level and hold it.

Stopping rule: Stop splitting a branch when its leaf is a testable hypothesis — something you could confirm or kill with data, an interview, or one analysis. If a leaf is still too broad to test, it is not a leaf yet; split it again.

Tag every assumption. Any node built on something the user didn't confirm in Step 1 — an inference, a judgment call, or a filled gap from "proceed with assumptions" — gets tagged [assumption — verify] directly on that node. This keeps guesses visible instead of blending them into confirmed facts, and is what the assumption-validation loop (Step 7) later resolves.

Work out the full tree structure now. It will be rendered as a visual tree diagram in the HTML report (Step 6) — or, only if HTML output isn't possible, as a markdown/ASCII diagram, e.g.:

Why did EBITDA margin fall 4pts in H2 2025?
├── Revenue side (margin = f of revenue mix)
│   ├── Price realization dropped
│   │   ├── Discounting deepened  ◄ leaf: testable
│   │   └── Mix shifted to lower-priced SKUs  ◄ leaf: testable
│   └── Volume fell in high-margin lines  ◄ leaf: testable
└── Cost side
    ├── Variable cost per unit rose
    │   ├── Input/commodity prices up  ★ leaf: testable
    │   └── Yield/waste worsened  ◄ leaf: testable
    └── Fixed costs rose
        └── New facility ramp / headcount  ◄ leaf: testable

Step 3: Run the MECE Audit

Before prioritizing, audit the tree explicitly against these four checks — this is what separates a real issue tree from a bullet list, and it will be shown as a pass/fail table in the final report:

CheckTest
OverlapFor each level, could a single root cause land in two branches? If yes, the branches overlap — fix them.
Sum-to-totalDo the branches at each level, taken together, account for 100% of the parent? Name what is missing if not.
No mixed levelsDoes any single level mix causes with symptoms, or causes with solutions? Separate them.
No kitchen sinkIs any level >5 branches? If so, group into 2–4 super-branches.

If any check fails, revise the tree before moving on — the report should never present a tree that fails its own audit.


Step 4: Prioritize (80/20) — Then Confirm with the User

An unprioritized tree is an unbounded research project. Star the 2–3 branches or leaves most likely to contain the answer, each with a one-line justification based on impact × likelihood:

★ Variable cost per unit rose — H2 overlapped the commodity spike; largest plausible margin hit. (high impact × high likelihood)

Be honest about likelihood — use base rates and known facts, not the most interesting branch.

Checkpoint — wait for confirmation before Step 5. Present the tree, the MECE audit result, and the proposed stars together, then ask:

Do these starred branches match what you know? Reply with different numbers to re-star, or "confirmed" to proceed.

This is where the user's own knowledge is most likely to overturn your guess — don't spend effort building the Step 5 data-request table on stars they'd have rejected. Wait for their reply.


Step 5: Convert Starred Leaves to Data Requests

For each starred leaf, produce one row. This is the payoff: the tree becomes a set of precise, bounded instructions an analyst or data agent can execute — never "look at the data and find insights."

HypothesisEvidence that would confirm / kill itPrecise analysis request
Input prices drove the variable-cost riseConfirm: unit input cost up >X% in H2, tracking the margin drop. Kill: input cost flat while margin still fell."Pull monthly per-unit input cost by material category, Jan–Dec 2025; overlay against unit gross margin; quantify the correlation and the pts of margin explained."

Each analysis request must be specific, bounded, and testable — name the metric, the segment, and the time window.


Step 6: Render the Report

Preferred: one self-contained HTML page. Assemble everything from Steps 1–5 into a single HTML document with these sections, in order:

  1. Header — the framed question (Step 1) and a badge stating Diagnostic or Solution tree, plus a count of open [assumption — verify] tags if any remain.
  2. Tree diagram — the MECE tree from Step 2, rendered as a nested visual structure (indented nested <ul>/<li> with connector styling, or a simple boxes-and-lines layout). Mark leaves distinctly (e.g. a small "testable" tag), mark any [assumption — verify] node with a visibly distinct tag (e.g. a dashed border or a "?" badge), and give starred leaves (Step 4) a visible highlight (e.g. a star icon or accent border/background) directly on the tree — don't make the reader cross-reference a separate list to find any of this.
  3. MECE audit — the Step 3 checklist as a compact pass/fail table, with a ✓/✗ per row and a one-line note for any failed-then-fixed check.
  4. Prioritization — the starred branches/leaves from Step 4 as callout cards, each with its impact × likelihood justification.
  5. Hypothesis → evidence → action table — the Step 5 table, styled as a proper HTML table (not a markdown table dumped into a <pre>).
  6. Next moves — a numbered list (see Step 7) the user acts on by replying in chat, not by clicking anything in the page.

Build requirements:

  • Fully self-contained: inline <style>, no external stylesheets, fonts, or scripts.
  • Theme-aware: support both light and dark viewing (respect prefers-color-scheme, and if the host environment stamps a data-theme attribute, honor that as an override).
  • Responsive: no fixed pixel widths that overflow; wide elements (the tree, the table) scroll within their own container rather than the whole page.
  • Clean, professional styling appropriate to a consulting deliverable — generous whitespace, clear typographic hierarchy. No decorative clutter.
  • House palette, set as CSS custom properties at :root and overridden under both @media (prefers-color-scheme: dark) and [data-theme="dark"]:
    • Light: paper background #F7F7F4, charcoal ink #1B2430, deep forest green #2F6F5E as the primary accent (headers, borders, tags), one soft gold #C9A961 reserved for a single highlight only (e.g. starred leaves) — not spread across multiple elements.
    • Dark: charcoal #1B2430 background, paper #F7F7F4 ink, a lightened forest green (e.g. #4E9484) as the accent so it still reads on a dark background, the same soft gold #C9A961 for the one highlight.
    • Muted and understated throughout — no saturated brights, no gradients, no corporate-flashy color blocking.

How to render the HTML: if the current session has an Artifact-rendering tool available, load its design-guidance skill first if one is required, write the HTML to a file, and publish it that way so the user gets a viewable page. Use a stable, descriptive title (e.g. issue_tree_<short_problem_slug>) so re-renders in the same conversation update the same page rather than minting a new one each time.

Fallback: markdown/ASCII in chat. If HTML cannot be produced or rendered in the current session (no file/artifact capability, or the user asks for it plainly), produce the same content directly in the chat response instead, in this order:

  1. The ASCII tree diagram from Step 2, with starred leaves marked ★ and other leaves marked ◄ leaf: testable.
  2. The MECE audit as a markdown table (Step 3).
  3. Starred branches as a bulleted list with ★ and the impact × likelihood justification (Step 4).
  4. The hypothesis → evidence → action table as a markdown table (Step 5).
  5. The next-moves numbered list (Step 7).

Say explicitly that this is the markdown fallback and why (e.g. "no page-rendering tool available in this session").


Step 7: Offer Next Moves

Close with a numbered menu the user can reply to by number:

  1. Drill down — expand a starred branch into its own detailed sub-tree.
  2. Flip to a solution tree — once a root cause is confirmed by data, decompose the fix.
  3. Validate assumptions — go check the [assumption — verify] tags against reality; come back with confirmations or corrections and I'll update only the affected branches, re-run the MECE audit and prioritization on what changed, and re-render — not rebuild the whole tree.
  4. Bring data — paste findings; I'll prune dead branches, re-prioritize, and re-render the report.
  5. Hand off to expected-value-calculator — once solution options are defined with payoffs, evaluate them.
  6. Hand off to thoughtful-execution — once solution pathways are enumerated but the right one isn't knowable without testing, turn them into hypotheses and an experiment plan.

Proceed only on the user's selection — wait for their reply.


Tone & Style

  • Structure first, opinions second. The tree is the deliverable; do not editorialize before it exists.
  • Show the MECE audit every time — checkable criteria, not "trust me, it's MECE."
  • Keep branch labels short and parallel (all nouns, or all "X did Y" clauses) — parallelism makes overlaps visible.
  • Never fake exhaustiveness. If a level cannot be made cleanly MECE, say so and add a labeled "Other" bucket rather than pretending.
  • Round numbers; flag every probability and estimate as a judgment call, not a fact.

Edge Cases

  • Cause already known: Skip the diagnostic framing in Step 1; go straight to a solution tree for the confirmed cause.
  • User insists on >5 Level-1 branches: Group them into 2–4 super-branches and show the grouping — do not just accept the list.
  • Purely qualitative problem (no arithmetic identity): Decompose by process stage, stakeholder, or lifecycle phase; the MECE audit still applies.
  • Data arrives mid-session: Prune branches the data rules out, re-run the 80/20 prioritization on what remains, rebuild the data-request table for the surviving leaves, and re-render the HTML report.
  • Analytics / ML problem: Level 1 is usually {data-level issues, model-level issues}; drive leaves to hypotheses like "feature drift in variable Z" that map directly to a specific query.
  • Two problems tangled together: Separate them into two trees; ask which to build first.
  • No HTML-rendering capability in the session: Use the markdown/ASCII fallback in Step 6 and say so explicitly — don't silently degrade without naming why.
  • User validates assumptions (some confirmed, some refuted): clear the tag on confirmed nodes. For refuted ones, revise or prune that branch; if a refuted assumption undermines a starred branch, drop the star and promote the next-most-likely branch, then re-run Steps 3–5 for just the affected path — don't rebuild branches nothing changed on.
  • User says "proceed with assumptions" at Step 1: build the full tree with every gap tagged [assumption — verify], and say plainly that this is a first-draft tree pending validation.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.