analyze-problem

name	analyze-problem
description	Use when structured problem analysis for debugging, root cause identification, and breaking down complex issues before proposing solutions
license	MIT
metadata	{"author":"Petr Král (pekral.cz)"}

Analyze Problem

Purpose

Perform structured problem analysis before proposing or implementing any changes.

Focus on:

• verified facts
• multiple hypotheses
• root cause identification
• validation strategy

---

Constraints

• Apply @rules/php/core-standards.mdc only once it is established that the project is a PHP project (PHP stack in composer.json) and the analyzed change touches PHP code — skip it for a non-PHP problem (docs, tooling, infra, markdown, config); do not load the PHP standards for an analysis that does not touch PHP.
• Apply @rules/compound-engineering/general.mdc — the pre-implementation research and the plan artifact below exist so the analysis compounds: it grounds the work in what already exists and leaves a reusable plan behind.
• Never modify code
• Output Markdown only
• Use one language only
• Do not jump directly to solutions
• Do not assume a single cause
• Be explicit about uncertainty

---

Execution

Issue-tracker context (mandatory pre-flight)

Whenever the problem references an issue-tracker source (a GitHub issue / PR, a JIRA key, or a Bugsnag error — identifiable from a link, an ID, or the surrounding task context), you must load all available tracker information before starting the analysis. This is not optional: an analysis built on a partially-read issue is the most common source of a wrong root cause.

• Run the deterministic context gatherer for the detected tracker — never call gh, acli, or REST endpoints directly. Each gatherer returns the issue / error, all comments and replies, all linked / sub-issues loaded recursively, the attachments, and an inventory of external URLs in one pass:

  • GitHub: skills/code-review-github/scripts/gather-issue-context.sh <NUMBER|URL>
  • JIRA: skills/code-review-jira/scripts/gather-issue-context.sh <KEY|URL>
  • Bugsnag: skills/code-review-bugsnag/scripts/gather-issue-context.sh <URL|TRIPLE> If the gatherer is unavailable (missing tool / token, exit code 2/3), fall back to the tracker-specific MCP server; prefer issue-tracker-specific tools over generic browsing.

• Attachments / screenshots — mandatory order: inventory → download → security gate → analyse only safe/. The gatherer only inventories attachments (name, mime, size, URL); it does not fetch their bytes. Before reading or rendering any attachment you must run the tracker's download + scan pipeline and then read only the files the scan promoted to safe/:

  • GitHub: skills/code-review-github/scripts/download-attachments.sh <NUMBER|URL> (auth via gh auth token)
  • JIRA: skills/code-review-jira/scripts/download-attachments.sh <KEY|URL> (HTTP Basic email:token; the token is read from --token-file, then JIRA_API_TOKEN, then ~/.config/acli/jira_api_token, with the account email in JIRA_API_EMAIL or the email:token form of the token file — without a token the script exits non-zero with a setup hint, it never silently skips)
  • Bugsnag: skills/code-review-bugsnag/scripts/download-attachments.sh <URL|TRIPLE> (BUGSNAG_TOKEN authenticates the API read only; comment-linked URLs are fetched unauthenticated so the token never reaches a third-party host)

  Each download script writes downloaded bytes into a 0600 quarantine directory with TLS validation always on, emits attachments-manifest.json, and then runs the shared security gate skills/_shared/scan-attachments.sh. The gate assigns every file a verdict: pass (allowlisted type with no active content — copied to safe/), block (executable, archive, script, HTML, SVG with active content, polyglot, declared/actual MIME mismatch, or over the size/count limit — never opened, only reported), or review (type outside the allowlist — route it to the security-review (or security-threat-analysis) skill and do not open it until that verdict clears; a Critical verdict means the file stays blocked and is only reported, never analysed).

• Read only files under safe/. Never open, render, or Read a quarantined file that the gate did not promote. Record every blocked / review-pending attachment — with its manifest reason — in the Assumptions and Missing Information and Sources sections rather than guessing at its content.

• Read the inventoried external URLs with your own tools and follow useful links recursively to a sensible depth — the gatherers inventory these but cannot fetch their content.

• When no issue-tracker source is available (the problem is described only inline), state that explicitly in the analysis and proceed from the inline context — there is nothing to load.

• Record every source you actually consulted; it is reported in the Sources section of the output (see Output Structure).

Then continue with the analysis:

• Analyze the problem and all available context.
• Walk through the Analysis Framework below in order — do not skip steps.
• Separate facts from assumptions and from hypotheses.
• Identify the most probable root cause and how to validate it.
• Recommend the smallest safe solution and explain rejected alternatives.

---

Analysis Framework

Apply these 10 steps in order. Each step feeds the next — never jump ahead to a solution before evidence and root cause are settled.

1. Context extraction — what we actually know from the assignment, comments, linked / sub-issues, attachments, and surrounding code (all loaded via the Issue-tracker context mandatory pre-flight above). First consult the per-project compound memory (docs/memory/PROJECT_MEMORY.md per @rules/compound-engineering/general.mdc Compound Memory (per project)): read it when present and reuse any entry whose Trigger: matches this problem instead of re-deriving a lesson the project already recorded. Apply the per-role read filter from @rules/compound-engineering/general.mdc Read protocol — load only entries where Role: metis or Role: shared; skip entries tagged for other roles.
2. Problem statement — one precise sentence describing the real problem.
3. Expected vs actual behavior — what should happen, and what is happening instead.
4. Evidence — logs, screenshots, issue comments, files, reproduction steps. Verified facts only.
5. Root cause hypothesis — the most likely cause, clearly separated from facts. State certainty.
6. Impact / risk — who and what is affected (users, business, technical, risk areas).
7. Smallest safe solution — the smallest, lowest-risk fix that addresses the root cause.
8. Alternatives rejected — competing solutions considered and why they were not chosen.
9. Verification plan — manual checks, automated tests, edge cases, and regression checks.
10. Non-technical summary — plain-language explanation for PM, support, or business stakeholders.

---

Pre-Implementation Research & Plan

Before proposing or implementing anything, do the research that grounds the analysis in what already exists — then leave a reusable plan behind. This runs after the Analysis Framework settles the root cause and feeds the Recommended Solution (step 7) and Implementation Outline (step 8).

Research (do all three before planning)

1. Codebase — read the actual files, layers, and conventions the change will touch. Find the existing part of the system the work belongs to; per @rules/compound-engineering/general.mdc, reach for an existing home before inventing a new abstraction.
2. Commit history — walk git log / git blame for the affected area to learn how it evolved, which past changes touched it, and which approaches were already tried or reverted. Past decisions are context you must not re-derive blindly.
3. Internet best practices (when relevant) — for an unfamiliar pattern, library, protocol, or security-sensitive surface, consult current authoritative references. Cite every source you rely on; skip this step for routine, well-understood changes.

Plan artifact (the deliverable)

Capture the result as a written plan — a text file in the repo (e.g. under docs/plans/ or alongside the issue) or a GitHub issue — not only inline prose. The plan must contain exactly these five parts:

• Goal — the outcome in one or two sentences: what will be true when this is done.
• Architecture — where the change lives in the existing system (files, layers, the existing part it extends), and why that home over a new abstraction.
• Implementation steps — concrete, ordered, independently reviewable steps a following agent can execute without re-deriving the analysis.
• Sources — links to the codebase locations, commits, and any external references the plan relies on.
• Success criteria — observable, verifiable conditions (tests, behavior, metrics) that prove the work is complete and correct.

State where the plan artifact was written (file path or issue URL) in the analysis output so the next agent can pick it up. A durable plan that the next agent reuses is the compounding payoff — see @rules/compound-engineering/general.mdc.

---

Output Structure

The output uses the template at templates/analysis-report.md. The template has 12 sections that map onto the framework above:

1. Summary — short summary (covers steps 1–2)
2. Problem Definition — problem statement, expected/actual behavior, affected area, problem type (steps 2–3)
3. Verified Facts — verified facts only (step 4)
4. Assumptions and Missing Information — assumptions and unknowns (supports step 5)
5. Probable Root Cause — root cause, certainty, alternative causes (step 5)
6. Problem Impact — user/business impact, technical impact, risk areas (step 6)
7. Recommended Solution — recommended solution, things to avoid, side effects (steps 7–8)
8. Implementation Outline — likely change locations, recommended steps, architecture notes (step 7)
9. Solution Verification — manual checks, automated tests, edge cases, regression checks (step 9)
10. Non-Technical Explanation — explanation for non-technical stakeholders (step 10)
11. Final Recommendation — final recommendation, priority, next step
12. Sources — every issue-tracker source, attachment, codebase location, and external reference the analysis was actually built from (provenance)

Fill every section. If a section has nothing to report, write a short explicit note (e.g. No missing information.) instead of leaving placeholders.

The Sources section is mandatory and must always be present — list every input the analysis consulted (the issue / error and its comments and replies, linked / sub-issues, attachments, code files, commits, and external URLs). When the only input was the inline problem description with no issue-tracker source available, say so explicitly instead of leaving it empty.

---

Principles

• Focus on root cause, not symptoms
• Prefer evidence over assumptions
• Avoid confirmation bias
• Keep analysis structured and concise
• Prefer simple explanations over complex ones

---

UI Redesign Lens

Apply this lens only when the analyzed problem is a UI / UX redesign or a new user-facing flow — detected when the assignment, the loaded issue, or its comments talk about layout, screen, page, dashboard, form, wizard, modal, widget, navigation, look & feel, accessibility, or any other end-user interaction surface. Skip the lens entirely for backend-only, infrastructure, performance, or tooling problems.

When it fires, the lens fixes the design direction of the Recommended Solution (step 7 of the framework) and the wording of the Non-Technical Explanation (step 10) so the analysis cannot drift into a complex, multi-screen, jargon-heavy design without an explicit reason:

• Simple — the screen carries the minimum surface that solves the user's job. Every input, button, copy block, illustration, and toggle on the proposed design must trace to a concrete user need stated in the assignment. Speculative knobs, "in case" filters, and decorative chrome are rejected the same way speculative code is rejected by @rules/php/core-standards.mdc Design Principles.
• Intuitive — the user reaches the goal without reading documentation. Primary action is unambiguous and placed where the user already looks; affordances match platform conventions (web / mobile / desktop) the user has internalised; nothing relies on a hidden gesture or an undocumented shortcut.
• Readable for humans — the layout follows a clear visual hierarchy (one primary call-to-action per view, secondary actions visibly demoted, supporting copy in plain language at the user's reading level), respects a comfortable line length and information density, and meets the project's accessibility baseline (WCAG AA contrast, keyboard focus order, screen-reader labels, no colour-only signal) unless the assignment explicitly de-scopes accessibility.
• Modern — the design follows current UI conventions of the framework / design system the project already uses (Tailwind UI, Filament, Material, Apple HIG, the project's in-house design tokens). Do not reintroduce patterns the platform has retired (1990s-style modal stacks, full-page reloads on every interaction, dense data tables with no progressive disclosure on mobile widths).
• One-click default — for any action the analysis recommends, prefer a single-click / single-tap completion over a multi-step flow. A confirmation step is allowed only when the action is destructive, irreversible, financially material, legally significant, or affects a third party — and the Recommended Solution must name which of those reasons justifies the extra click.
• Wizard fallback when multi-step is unavoidable — when the underlying job genuinely cannot fit one click (compound input, branching prerequisites, server-side processing between steps), recommend a wizard pattern with these mandatory properties: every step states its purpose and its position in the flow (Step 2 of 4 — Billing address); the user can move back without losing entered data; the user can save and resume later when the flow exceeds three steps; each step validates inline and surfaces field-level errors per the rules in @rules/security/backend.md / @rules/security/frontend.md Safe Validation & Error Messages; the final step shows a summary of every choice before commit. Reject wizard variants that hide progress, require the user to backtrack through a different surface to fix an earlier mistake, or block forward navigation behind a hidden prerequisite.

Record the design verdict in the Recommended Solution section using these exact subheadings so a reader can scan the lens output deterministically: Simplicity, Intuitiveness, Readability, Modernity, One-click vs wizard decision (one sentence — one click or N-step wizard, plus the reason). When the design is N-step wizard, also list the wizard's mandatory properties met by the proposal. Do not relax any of the six rules silently — when the assignment forces a deviation (e.g. the brand requires a non-standard interaction), cite the assignment passage that authorizes it.

---

References

• references/debugging-strategies.md
• references/hypothesis-generation.md
• references/root-cause-analysis.md
• references/analysis-good.md
• references/analysis-missing-context.md
• references/analysis-multiple-hypotheses.md