Issue Investigator

Issue Investigator

Use this skill to understand an issue before deciding what to build, fix, configure, roll back, test, monitor, or clarify.

This is intentionally not only a single-tracker bug-fix skill. It investigates many issue types across many tracker platforms and produces an evidence-based result before recommending the next action. It must not jump directly to implementation.

⚠️ PREFLIGHT — Execute before ANY other action

This skill participates in the [Company Brain](../../../../docs/company-brain.md) self-improving loop. Before context discovery, investigation, or evidence gathering, run this ONE command. No arguments are required; the script detects the project and task id from config, GitHub environment, branch, or cwd:

bash scripts/start-task.sh --skill issue-investigator=0.35.0

If detection is wrong, rerun with explicit values:

bash scripts/start-task.sh   --skill issue-investigator=0.35.0

If scripts/start-task.sh is not at the current cwd, use the installed agent-skills/scripts/start-task.sh or .agent-skills/scripts/start-task.sh path. If you cannot run the wrapper after locating it, run the three individual steps:

1. python3 scripts/org-memory.py read (non-fatal if missing)
2. python3 scripts/project-memory.py read (init the skeleton if missing)
3. python3 scripts/blackboard.py init --project

The output IS your starting context. Do not re-discover facts already recorded in project memory. Every Common gotchas bullet is a verified constraint; every Build & runtime bullet is the authoritative build command.

After the task, run:

bash scripts/finish-task.sh --skill issue-investigator --summary ""

For blocked or needs-context runs, pass --status blocked or --status needs-context; the finish wrapper preserves scratch in those states. See [docs/project-memory.md](../../../../docs/project-memory.md) for the full contract.

> Skipping these steps is the #1 failure mode. Task size does not waive them: > a small issue-context lookup and a full root-cause investigation both start > and finish through the lifecycle wrappers.

> Safety floor. This skill is read-only by default and inherits the > [destructive-action safety policy](../../../../docs/destructive-action-safety.md). Every > check the agent proposes to the user must be classified as read-only or mutating; > mutating checks are not proposed by this skill at all and belong in a > [software-engineer](../../SKILL.md) operator runbook. The agent must never invoke a > credential discovered during investigation (see > [Discovered-credential protocol](#discovered-credential-protocol)) and must never ask the > user to paste a secret into chat.

Purpose

• Read and understand the full issue context from tickets, descriptions, comments, screenshots,

logs, linked documents, related issues, and codebase evidence.

• Classify the issue type and distinguish expected behavior from actual behavior.
• Reproduce the issue locally or in a safe environment when useful and possible.
• Identify suspected or confirmed root cause with real evidence.
• Recommend the next action: fix, clarification, rollback, configuration change, data correction,

test addition, monitoring improvement, product decision, or no code change.

• Produce reliable issue context for [code-reviewer](../code-reviewer/SKILL.md) and implementation

planning for [software-engineer](../../SKILL.md).

When To Use

• Bug investigation.
• Production incident investigation.
• Regression investigation.
• Support ticket investigation.
• New feature clarification.
• Technical task analysis.
• Tracker ticket (Jira key, GitHub issue URL, GitLab issue URL, etc.) refinement before implementation.
• Root-cause analysis before fixing.
• Review preparation when expected behavior or issue context is unclear.

When Not To Use

• Do not use to implement the fix; hand confirmed or suspected fix work to

[software-engineer](../../SKILL.md).

• Do not use to invent acceptance criteria for unclear product behavior; hand that to

[product-owner](../../../product-owner/SKILL.md).

• Do not use for final PR approval; hand the diff to [code-reviewer](../code-reviewer/SKILL.md).
• Do not continue when the only available input is a vague symptom with no issue source, affected

area, expected behavior, or reproduction clue.

Related And Reused Skills

• [software-engineer](../../SKILL.md): use for technical code-path analysis, architecture

constraints, implementation feasibility, validation commands, and production-risk judgment.

• [code-reviewer](../code-reviewer/SKILL.md): use after a fix or implementation exists and needs

issue-aware review.

• [product-owner](../../../product-owner/SKILL.md): use when intended behavior, business value,

scope, UX expectation, or acceptance criteria are unclear.

• [manual-tester](../../../manual-tester/SKILL.md): use for reproduction scenarios, exploratory

validation, defect evidence, and retest guidance.

• [test-automation-engineer](../../../test-automation-engineer/SKILL.md): use when the

investigation identifies stable regression scenarios that should be automated.

• [delivery-planner](../../../delivery-planner/SKILL.md): hand off when the investigation itself

is multi-phase (e.g., reproduce → bisect → propose fix path → validate fix in staging) and a single investigator pass cannot hold all of it without losing accuracy. The planner produces a destination brief plus phased plan; this skill then runs one phase per dispatch instead of trying to keep the entire investigation in one growing context. Do not invoke the planner during a normal single-pass investigation — it is reserved for genuinely multi-step work.

Issue investigation owns facts, evidence, classification, root cause, and next-step recommendation. It does not own broad implementation quality; that belongs to [software-engineer](../../SKILL.md) and [code-reviewer](../code-reviewer/SKILL.md).

Required Inputs

Accept any of these as the starting issue source:

• Jira ticket key or URL (or equivalent tracker key from GitLab, Azure DevOps, etc.).
• GitHub issue URL or number.
• Support ticket, production incident, regression report, bug report, feature request, task

description, or user-provided issue brief.

• Affected repo, service, component, environment, release, branch, or version.
• Expected vs actual behavior, if known.
• Screenshots, logs, traces, request/response examples, deployment notes, CI output, monitoring

links, or related documents.

If the issue source is missing or too vague, ask focused questions. If access to a referenced system is unavailable, say what could not be inspected and request the smallest useful excerpt.

Stopping Conditions

Stop and return a root cause status of unknown when:

• The issue source cannot be accessed and the user did not provide enough direct detail.
• Expected behavior cannot be established from ticket, product, docs, tests, or user context.
• Reproduction would require unsafe production mutation or sensitive data exposure.
• Evidence is too weak to support the recommended next action.
• Root-cause hypotheses are plausible but untested; mark them suspected, not confirmed.

Required Environment

Run this setup preflight before investigating.

Detect execution mode ([docs/execution-modes.md](../../../../docs/execution-modes.md)): if AGENT_SKILLS_MODE is set to local-workspace or in-repo, use it; else if ${WORKSPACE_ROOT}/.env is present → local-workspace; else if .agent-skills.yml exists at the repo root → in-repo; else continue only when the user supplied the issue details directly and no repository/Jira lookup is needed. Otherwise warn and stop because the investigation would be based on incomplete context.

For tracker tickets, usable tracker access is required unless the user provides the ticket summary, acceptance criteria, key comments, linked-doc excerpts, and affected environment details directly. .jira-config.yml is optional when the Jira environment variables work. If a Jira key or URL is supplied but the ticket cannot be read and no direct ticket details are provided, stop instead of producing a low-confidence investigation.

Mandatory auth discovery before declaring the tracker/document-store inaccessible. The agent must walk the [auth discovery order](../../../../docs/auth-discovery.md#discovery-order) before reporting that the issue tracker or linked document store is unavailable:

1. Check .agent-skills.yml for jira: / confluence: (or equivalent tracker) host metadata.
2. Check .jira-config.yml for placeholder structure (${JIRA_HOST}, etc.).
3. Check .env and .env.local for actual values.
4. Check process environment variables.
5. Run python3 scripts/auth-preflight.py (or pass --require-jira when Jira is in scope).

The preflight resolves placeholders, validates required fields, and exits 0/1/2 without printing any secret values.

1. Only after the preflight returns non-usable should the agent ask the user — and the ask must

name the specific missing or unresolved fields (never the secret value).

Locate config files before claiming any are missing. Run python3 scripts/locate-config.py — .env / .jira-config.yml (or equivalent tracker config) are written by setup.init to the parent workspace folder, not the repo cwd. "Not in cwd" is not "not in the workspace". Reporting the former as the latter is a workflow failure.

Project memory. Before context discovery, run python3 scripts/project-memory.py read . If a recorded Common gotchas entry matches the symptom under investigation, cite it in the investigation report and verify it before proceeding. After investigation, append any newly-discovered durable fact (the actual reproduction trigger, a hidden config flag, a service dependency) under Common gotchas. See [docs/project-memory.md](../../../../docs/project-memory.md).

Treat unresolved ${VAR} placeholders in .jira-config.yml as incomplete configuration, not as missing auth. The fix is to load .env (or set the variable in the process environment), not to ask the user for credentials. Most Jira CLIs do not expand ${VAR} placeholders themselves; either source .env first (set -a && source .env && set +a) or rely on the auth preflight.

If config exists but is incomplete, the investigator must report:

• which non-secret fields are unresolved (e.g. ${JIRA_HOST} not set in .env),
• which secret fields are missing (redacted, never echoed),
• the smallest fix (typically: rerun ./setup.init or add the missing key inside the

# >>> agent-skills setup.init block of .env),

• whether the investigation can continue from supplied issue text alone (it can, with a

clearly-marked limitation).

Required setup variables:

• WORKSPACE_ROOT — required in local-workspace mode for resolving repos,

cache, and local context. In in-repo mode the repository root is used.

• PROJECTS_JSON — required in local-workspace mode for matching affected

repos/services to stack and commands. In in-repo mode the project: block in .agent-skills.yml replaces this.

• JIRA_HOST, JIRA_API_TOKEN, JIRA_AUTH_TYPE — required only for Jira

tickets, used for Jira ticket lookup.

• JIRA_LOGIN — required for basic auth and recommended for bearer auth; used as

Jira CLI identity.

• JIRA_CONFIG_FILE — optional Jira CLI config path.
• CONFLUENCE_HOST, CONFLUENCE_API_TOKEN — required only when linked docs

require them, used for Confluence lookup.

• ISSUE_INVESTIGATOR_CACHE_DIR — optional cache dir for fetched ticket/doc

summaries; default ${AGENT_SKILLS_CACHE_DIR:-${WORKSPACE_ROOT:-$REPO_ROOT}/.cache/issue-investigator}.

• ISSUE_INVESTIGATOR_CACHE_TTL_HOURS — optional cache TTL; default 24.
• ENVIRONMENTS_JSON — optional JSON array of deployed-environment pointers

(name, type, access, sshtarget, kubectlcontext, namespace, logpaths, logaggregator, notes). Stores POINTERS ONLY — never credentials. When present, the investigator uses these handles for the read-only environment evidence channel described in [Environment evidence access](#environment-evidence-access). When absent, the investigator falls back to asking the user where the affected environment lives.

For GitHub issues, prefer the authenticated gh CLI when available. Do not require new secrets in this public skill unless the user's environment already uses them.

If setup is incomplete, output:

> Missing required setup: `. I will not continue with issue-aware investigation > because the result would be based on incomplete context. Add/update ${WORKSPACE_ROOT}/.env > (local-workspace) or .agent-skills.yml at the repo root (in-repo — see > agent-skills/.agent-skills.example.yml`), provide the missing issue details directly, or rerun > without the unavailable issue source.

Required Workflow

0. Requirement Understanding Gate

This is the strongest place in the repository to apply the [requirement-understanding workflow](../../../../docs/requirement-understanding.md). Investigation is where most agents quietly assume the requirement and then justify the assumption with evidence. Run the twelve-step gate before step 1 and emit the Requirement Understanding block in the user-facing output above the rest of the investigation result.

The gate output for an investigation must include, in addition to the standard fields:

• The classified issue type from step 2 below, with confidence.
• Expected vs actual behavior, distinguishing ticket facts, log/code evidence, and

agent assumptions — not merged into one paragraph.

• Both a root-cause confidence (how sure the agent is about the cause) and a

requirement-understanding confidence (how sure the agent is about what the system should be doing). These are independent: a high-confidence root cause for the wrong requirement is worse than no investigation at all.

• A list of missing evidence and the cheapest read-only check that would close each gap.

Binding rules (from the workflow's confidence-to-action section):

• unknown — the agent cannot describe expected behavior, the issue source is missing

inputs, or candidate interpretations cannot be discriminated. Readiness is NEEDS_CLARIFICATION or NEEDS_EVIDENCE. Do not recommend a fix, rollback, configuration change, or data correction. Permitted recommendations are monitoring or alerting improvement, product clarification, or documentation.

• low — expected behavior is partially known but at least one load-bearing assumption is

unverified, or there is an unresolved contradiction. Recommendations limited to clarification, monitoring, documentation, or further investigation. Do not promote a hypothesis to confirmed and do not hand off a code fix recommendation.

• medium — may run the [three-hypothesis discipline](#three-hypothesis-discipline), the

[regression triage](#regression-triage-when-the-issue-worked-before) ladder, and propose bounded read-only checks the user can run. Recommendations may include rollback (if a clear introducing commit exists) or code fix only when the recommendation matches the evidence gate in step 5. Every load-bearing assumption stays visible.

• high — may recommend a confirmed-cause action (code fix, rollback, `configuration

change, data correction) when the evidence gate in step 5 is met. The first plausible explanation is not high` — it requires disconfirming checks that were run or judged unnecessary because evidence already excluded the alternatives.

A recommendation must never be more confident than the lower of root-cause confidence and requirement-understanding confidence. If the agent is sure about the cause but unsure about what the system should do

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: wamalalawrence
• Source: wamalalawrence/agent-skills
• License: MIT

Install and usage instructions live in the source repository linked above.