About

Imported from shipshitdev/skills (skills/why/SKILL.md). Install upstream with npx skills add shipshitdev/skills --skill why. Copyright stays with the author (MIT).

Why

Name: why
Author: shipshitdev

Investigate the motivation behind code. Companion to how. how answers what the code does. why answers what forces led to its shape.

Historical context spreads across seven evidence categories. Enumerate available connectors at run time, query every available category in parallel, then synthesize with explicit confidence calibration. A null result is first-class evidence.

Contract

Inputs:

A why-question about a chunk of code, pattern, feature, or named decision

Outputs:

A confidence-separated, cited narrative with a coverage map

Creates/Modifies:

None

External Side Effects:

Read-only git, gh, and available issue/docs/chat/observability connectors. No writes.

Confirmation Required:

None

Delegates To:

None. May spawn one investigator per evidence category, then one synthesizer.

Operating posture

Evidence before narrative.
Precision over polish. Quote and cite.
Name the gaps.
Hedge when evidence is indirect.
Do not infer intent from code shape alone.

Read references/epistemics.md before synthesizing.

Step 1. Understand the target

Parse the question. If the target is vague, state the best guess from conversation context and proceed.

Step 2. Establish the code anchor

Before spawning investigators, gather file paths, line ranges, key symbols, recent commits, and PR numbers.

git blame -L <start>,<end> <file>
git log --follow -p -- <file>
git log --oneline -20 -- <file>
gh pr view <number> --json title,body,author,createdAt,mergedAt,labels,closingIssuesReferences,comments,reviews

Pass this seed to every investigator.

Step 3. Spawn parallel investigators

Discover available connectors (MCP servers, CLIs, APIs). Map each to one category from references/evidence-categories.md. Source control is always available through git and gh.

Launch one investigator per available category in a single message, on the fast cheap tier. Do not use a read-only sandbox that strips connectors. Investigators still write nothing.

Skip a category only with a written justification: no connector available, or the source is provably irrelevant. "Probably irrelevant" is not enough.

Each investigator gets references/investigator-prompt.md, its category playbook, the code anchor, and the user's question.

Step 4. Synthesize

Spawn one synthesizer on the strongest judgment tier. It gets all findings, including nulls, plus references/synthesizer-prompt.md and the epistemics file. Do not rewrite its confidence language.

Output format

The Question. Restate the ask.

The Code in Question. Paths, line ranges, symbols.

What We Found (direct evidence). Cited claims only.

What We Can Reasonably Infer. Hedged, with the inference chain.

Competing Hypotheses. When the record supports more than one story.

What We Don't Know. Specific gaps.

Sources Consulted. One line per category, including empties and skips.

If the why is a precursor to a change, convert findings into Preserve / Change / Avoid / Risk constraints.

Why procedure

Read why procedure when running this workflow. Apply the authorized scope and mode of this entry point to every step. Resolve other skills through this distribution’s active catalog; resolve resources relative to the installed skill directory.

Use it

Copy one of these into your project. Installing also returns the manifest and these snippets.

yaml

targets:
  - https://api.opensmartroute.ai/api/v1/registry/shipshitdev-skills-why/manifest   # or paste the manifest below

Manifest

An Open Capability Manifest: the router reads it to know what this does, what it costs and when to pick it.

shipshitdev-skills-why.ocm.jsonjson

{
  "ocm": "1",
  "id": "shipshitdev-skills-why",
  "kind": "skill",
  "name": "why",
  "description": "Investigate why code is shaped the way it is. Use for design rationale, regressions, postmortems, or data-backed thresholds. Queries available evidence categories in parallel, then returns a cited read on decisions and tradeoffs. Use how for runtime behavior.",
  "publisher": "shipshitdev",
  "version": "1.0.0",
  "capabilities": {
    "domains": [
      "coding"
    ],
    "tags": [
      "skill-md",
      "investigation",
      "rationale",
      "history",
      "evidence",
      "skills-sh"
    ],
    "languages": [
      "en"
    ]
  },
  "quality_prior": 0.6,
  "examples": [
    "Investigate why code is shaped the way it is. Use for design rationale, regressions, postmortems, or data-backed thresholds. Queries available evidence categories in parallel, then returns a cited read on decisions and tradeoffs. Use how for runtime behavior."
  ],
  "primary": false,
  "metadata": {
    "source": {
      "provider": "skills.sh",
      "repository": "https://github.com/shipshitdev/skills",
      "path": "skills/why/SKILL.md",
      "ref": "HEAD",
      "url": "https://github.com/shipshitdev/skills/blob/HEAD/skills/why/SKILL.md",
      "key": "shipshitdev/skills/skills/why/SKILL.md"
    },
    "license": "MIT"
  },
  "instructions": "# Why\n\nInvestigate the motivation behind code. Companion to `how`. `how` answers\nwhat the code does. `why` answers what forces led to its shape.\n\nHistorical context spreads across seven evidence categories. Enumerate\navailable connectors at run time, query every available category in\nparallel, then synthesize with explicit confidence calibration. A null\nresult is first-class evidence.\n\n## Contract\n\nInputs:\n\n- A why-question about a chunk of code, pattern, feature, or named decision\n\nOutputs:\n\n- A confidence-separated, cited narrative with a coverage map\n\nCreates/Modifies:\n\n- None\n\nExternal Sid",
  "cost": {
    "context_tokens": 871
  }
}

Fetch it by URL: GET /api/v1/registry/shipshitdev-skills-why/manifest?version=1.0.0

Reviews

Star ratings from people who tried it. One review per account; edit yours any time.

No reviews yet. Install it, try it, and be the first to rate it.