agentleFS
YomudoglyYomudogly/oh-my-agy/skills/analyze/SKILL.md

analyze

Skill4 starsChanged todayMITView on GitHub

[oh-my-agy] Read-only deep repository analysis returning a ranked synthesis with explicit confidence, concrete file references, and evidence-vs-inference boundaries. Use when the user says 'analyze', 'investigate', 'why does', 'what's causing', pastes a stack trace or runtime error log, or needs a grounded cross-file explanation before any changes.

72 other projects use a version of this, 1 of them edited.

Adopted by

Most recently taken up by

Used with

Projects with it also use constitution, revise and 10 more.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • ArvorCoSkill

    constitution

    Create or update the project constitution - personalized governance and coding principles. Use when starting a project or updating project standards. Triggers on: create constitution, update principles, set project rules.

    Also in 4 projects that use this

  • stormlightlabsSkill

    revise

    Address review comments on an open pull request and push the fixes. Use for /edit, /revise, or when asked to respond to review feedback on a PR number.

    Also in 3 projects that use this

  • DockerSkill

    write

    Write or edit reader-facing technical prose for immediate comprehension. Use for documentation, PR titles and descriptions, release notes, design documents, user-facing explanations, and substantive comments. Also use when asked to make writing clearer, more natural, less AI-generated, or easier to read. For documentation fixes, handles edits, formatting, self-review, and commits after research identifies what to change. Do not use for code-only tasks with no prose deliverable.

    Also in 6 projects that use this

  • ArvorCoSkill

    specify

    Create feature specification from natural language description. Use when starting a new feature or creating a spec. Triggers on: create spec, specify feature, new feature spec.

    Also in 5 projects that use this

  • H-mmerSkill

    submit

    Draft and submit a vulnerability report to the bug bounty platform. Reads scope.yaml for platform/program, uses brain + findings for content. Always drafts first for review.

    Also in 3 projects that use this

  • GoogleSkill

    quality

    Evaluates whether a GitHub issue is spam, empty, needs more information, or is OK to proceed.

    Also in 3 projects that use this

  • +1 more from ArvorCo

The file

We split this skill into the rules it gives an agent

8 rules. 0 are common, 6 are distinctive, and 2 are very specific to this project.

  • 0

    Common

    Most of the 62 edited versions we read keep these.

  • 6

    Distinctive

    This author's own choices. Worth a look.

  • 2

    Very specific

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

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Use $analyze to answer a repository question with grounded, read-only evidence.

    line 8
  2. Very specific:

    Do not use it for edits, implementation, a new product plan, a simple one-file lookup, or $team orchestration.

    line 18
  3. Distinctive:

    Read direct code paths and contracts first.

    line 24
  4. Distinctive:

    Stop when the question is answered with sufficient evidence, or name the smallest read-only probe that would resolve the remaining …

    line 32
  5. Distinctive:

    Prefer direct paths and higher-tier corroboration over lower-tier clues.

    line 50
  6. Distinctive:

    Do not edit files, run an implementation lane, or make recommendations the evidence cannot support.

    line 85
  7. Distinctive:

    Do not continue searching after the answer and confidence boundary are grounded.

    line 86
  8. Distinctive:

    If evidence is insufficient, report the limit explicitly rather than manufacturing certainty.

    line 87

“Common” is measured: kept by at least 6 in 10 of the 62 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

Analyze — Read-Only Deep Analysis

Use $analyze to answer a repository question with grounded, read-only evidence. Explain what the code most likely says; do not turn analysis into implementation or generic fix planning.

Shared operating, delegation, state, and verification invariants live in the oh-my-agy rules (rules/AGENTS.md).

Use when

  • The user needs a causal, architectural, behavioral, impact, or tradeoff explanation (including diagnosing a pasted stack trace or runtime error log).
  • The answer requires tracing multiple files or boundaries, or ranking plausible explanations.
  • The user needs confidence and concrete evidence before changing anything.

Do not use it for edits, implementation, a new product plan, a simple one-file lookup, or $team orchestration.

Inputs and method

  1. Restate the question and define the evidence-backed scope.
  2. Identify the smallest files, tests, configs, and docs likely to answer it.
  3. Read direct code paths and contracts first; trace boundaries only as far as needed.
  4. Compare competing explanations across distinct frames (code path, config/env/orchestration, measurement/artifact mismatch), rank them by the 6-tier Evidence Strength Hierarchy, and run a Rebuttal Pass against the leading explanation before synthesis.
  5. For --deep or high-ambiguity multi-subsystem mysteries, dispatch up to 3 parallel tracer subagents via invoke_subagent (one per causal frame: Code-path, Config/env/orchestration, Measurement/artifact mismatch) and synthesize their findings after cross-rebuttal.
  6. Whole-Repo Quality & Lean Audit Mode (--audit [path]): when invoked with --audit [path], map the codebase first (sh <plugin>/hooks/run.sh codebase-map <workspace> and sh <plugin>/hooks/run.sh scan-debt <workspace>, plus read-only coverage-map, docs-drift, and mcp-audit probes when test gaps, doc drift, or MCP configs matter), identify entry points, end-to-end data flows, and expected load (single-user script vs concurrent multi-user/process service), then inspect for (1) Bug (edge cases, caller disagreements), (2) Risk (security, data loss — escalate full STRIDE/agentic attack surfaces to $threat-model), (3) Scale (races, unbounded memory, $O(n^2)$ paths relative to assumed load), (4) Missing test on risky logic, (5) Speed, and (6) Lean (delete dead code/options, reuse existing repo helpers, stdlib/native replacement, yagni single-implementation wrappers, merge near-copies, split multi-job functions). Treat shortcut: <ceiling>, <upgrade> comments as intentional decisions unless expected load crosses the ceiling. Output at most 20 numbered findings grouped under Must fix, Should fix, and Nice to have, each with 4 concise parts (What this is, Problem with concrete input case, Fix preferring deletion, If we skip it), ending with Verdict:, Lean: -<N> lines, -<M> dependencies possible., Shortcut debt: <N> markers (<M> no-trigger), and Not checked:.
  7. Blast-Radius (--blast-radius <symbolOrFile>), Statechart (--statechart <moduleOrFlow>) & Architecture-Depth Surveys:
    • $analyze --blast-radius <symbolOrFile>: load references/blast-radius-and-statechart.md, run the 1-call codegraph_explore fast path (when indexed) plus grep / dirty-worktree fallback, and classify dependents into Direct Callers, Transitive Entrypoints / Routes / CLI, Shared State / Schema Coupling, and Missing Regression Coverage (certain | likely | unlikely | unverified with file:line).
    • $analyze --statechart <moduleOrFlow>: load references/blast-radius-and-statechart.md, extract explicit and implicit state transitions into a valid GitHub-flavored Mermaid stateDiagram-v2 diagram (quoted labels), and emit the Dead / Unreachable / Missing-Transition Audit Table (file:line).
    • When surveying module architecture generally, classify structural friction into 3 concrete buckets: (1) Shallow modules (pass-through wrappers whose interface is as complex as their body), (2) Hypothetical seams (abstractions/interfaces with only a single implementation), and (3) Logic behind the wrong seam (callers forced to know internal sequencing or state of a dependency).
  8. Stop when the question is answered with sufficient evidence, or name the smallest read-only probe that would resolve the remaining uncertainty.

Evidence discipline

Label every material claim as one of:

  • Evidence — directly shown by code, tests, generated artifacts, configuration, or docs.
  • Inference — a reasoned conclusion drawn from cited evidence.
  • Unknown — not settled by the repository evidence.

Rank evidence using the 6-tier Evidence Strength Hierarchy (strongest to weakest):

  1. Tier 1: Controlled reproduction, direct test/probe output, or source-of-truth artifact that uniquely discriminates between hypotheses.
  2. Tier 2: Primary artifact with tight provenance (file:line behavior, timestamped logs, git history, config snapshot).
  3. Tier 3: Multiple independent sources converging on the same mechanism.
  4. Tier 4: Single-source code-path inference that fits the symptom but is not uniquely discriminating.
  5. Tier 5: Weak circumstantial clues (naming, temporal proximity, stack order).
  6. Tier 6: Intuition, analogy, or speculation.

Prefer direct paths and higher-tier corroboration over lower-tier clues. Never present guesses as evidence or inference, and never overclaim certainty.

Output contract

Answer the asked question first and use this shape:

Question

Restated question, briefly.

Ranked synthesis

RankExplanationConfidenceBasis
1...High / Medium / Lowstrongest supporting evidence
2...High / Medium / Lowwhy it trails
3...High / Medium / Lowwhy it remains possible

Evidence

  • path/to/file:line-line — direct observation.
  • path/to/file:line-line — corroborating observation.

Inference

  • What the evidence most strongly implies.
  • Why weaker alternatives were down-ranked.

Intent-vs-Reality Diff (include when auditing docs, specs, or expected vs actual behavior)

Surface / ClaimExpected / Documented (source)Actual Code Behavior (file:line)Drift Classification
.........Match / Undocumented / Broken / Stale

Unknowns / limits

  • What the repository does not establish.
  • The next discriminating read-only probe, when useful.

Stop conditions

  • Do not edit files, run an implementation lane, or make recommendations the evidence cannot support.
  • Do not continue searching after the answer and confidence boundary are grounded.
  • If evidence is insufficient, report the limit explicitly rather than manufacturing certainty.

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.