OpenParable
Skip to content
← Back to skills

Investigate Issue

Testing & Quality
investigate-issue

Investigate Issue is an Agent Skill for testing & quality published in the psd-tools/psd-tools repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Investigate a GitHub issue and post structured findings as a comment. Use when the user wants to analyze a bug report, reproduce it, and share findings on the issue thread.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/psd-tools/psd-tools/blob/HEAD/.claude/skills/investigate-issue/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/investigate-issue, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

Step 0 — Identify the issue

Provided issue: $ARGUMENTS

If an issue number was provided, store it as ISSUE_NUMBER and continue to Step 1. If no issue number was provided, ask the user which issue to investigate, then store the answer as ISSUE_NUMBER.

Step 1 — Fetch the issue

gh issue view ISSUE_NUMBER --repo psd-tools/psd-tools --comments

Read the full issue body, title, and all comments. Understand:

  • What behavior the reporter expected
  • What behavior they observed
  • Any reproduction steps or sample files mentioned
  • The version of psd-tools they used

Step 2 — Reproduce or locate the root cause

Based on the issue description, investigate the codebase:

  1. Search for relevant code using grep or find in src/psd_tools/
  2. If the issue has a code snippet, try to reproduce it:
    uv run python -c "..."
    
  3. If the issue mentions a specific PSD feature, trace the code path:
    • High-level API: src/psd_tools/api/
    • Low-level parsing: src/psd_tools/psd/
    • Compositing: src/psd_tools/composite/
  4. Look for related tests in tests/ that may already cover (or fail to cover) the case

Classify the issue into one of these categories before writing the comment:

ClassificationWhen it applies
Bug (parsing)Wrong data read from the PSD binary
Bug (API)Wrong value exposed to the user
Missing featureBehavior not implemented
Already fixedThe bug no longer reproduces on main
UnreproducibleCannot reproduce without a sample file or more detail
By design / known limitationDocumented or intentional constraint (see Known Limitations in CLAUDE.md)
Needs composite depsOnly affects users without psd-tools[composite] installed
DocumentationUser misunderstood the API
DuplicateSame root cause as an existing issue

Step 3 — Draft investigation findings

Write a clear, structured comment in Markdown. Tailor the content to the classification:

## Investigation findings

**Classification**: [one of the categories above]

### Analysis

[2–4 paragraphs: what you found, where in the code the issue originates, and why it happens.
For "Already fixed", note the commit/PR that fixed it.
For "Unreproducible", list what you tried and what additional info is needed (sample PSD file, version, Python version, etc.).
For "By design / known limitation", cite the relevant Known Limitations entry.
For "Needs composite deps", explain which optional packages are required and how to install them.]

### Relevant code

[Point to specific files and line numbers, e.g. `src/psd_tools/psd/smart_object.py:123`.
Omit if not applicable.]

### Reproduction

[Minimal code that reproduces the bug. If unreproducible, omit this section.]

### Suggested fix

[Brief description of the approach to fix it.
Omit for "By design", "Already fixed", "Duplicate", and "Unreproducible" — use the Analysis section instead.]

Omit sections that are not applicable. Keep the tone neutral and technical.

Step 4 — Ask before posting

Show the user the draft comment and ask: "Ready to post this as a comment on issue #ISSUE_NUMBER?"

Do NOT post without explicit user confirmation.

Step 5 — Post the comment

Once the user confirms, write the comment body to a temp file and post via --body-file to safely handle multiline Markdown, backticks, and special characters:

cat > "${TMPDIR:-/tmp}/issue_comment_ISSUE_NUMBER.md" << 'EOF'
COMMENT_BODY
EOF
gh issue comment ISSUE_NUMBER --repo psd-tools/psd-tools --body-file "${TMPDIR:-/tmp}/issue_comment_ISSUE_NUMBER.md"

Print the URL of the posted comment.