issue-research

Sweep the codebase with Codex and write research artifacts for board issues.

Updated Aug 27, 2026
One-click install
npx skills add https://github.com/KMakayee/playbook --skill issue-research
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: issue-research
Source: https://github.com/KMakayee/playbook/tree/main/.claude/skills/issue-research
Command: npx skills add https://github.com/KMakayee/playbook --skill issue-research

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) and scripts (resource) components.

What problem does it solve?

It turns a board issue’s description and acceptance criteria into a grounded research artifact so implementation can start with clear choices, evidence, and constraints.

Core Features & Use Cases

  • Issue-scoped codebase research: Uses Codex to sweep relevant files and map the solution space against the issue’s goals.
  • Synthesis into decision-ready axes: Claude consolidates findings, fills gaps, audits dependencies, and produces a recommended approach.
  • Artifact-driven workflow: Writes a bounded output file at tasks/research-issue-$ARGUMENTS.md for the next phase (/issue-plan).

Quick Start

Ask for issue research for issue number 12 by running /issue-research 12.

Frequently Asked Questions about issue-research

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I turn a board issue into a build-ready plan with clear decision axes?

Issue research turns a board issue into a build-ready plan by sweeping the codebase and synthesizing evidence into decision axes. It validates prerequisites, maps the solution space against issue goals, and writes a research artifact with recommended approaches.

How do I generate implementation-ready research before planning software engineering tasks?

To generate implementation-ready research, run the research command with an issue number. It sweeps relevant files using Codex, synthesizes findings into decision-ready axes using Claude, and writes an artifact file containing evidence and recommendations for the next phase.

Do I need an existing issue file to run codebase research and synthesis?

Yes, you need an existing issue file. The research process validates prerequisites by looking up the issue in tasks/issues.md, preventing overwriting existing artifacts before composing the research prompt and executing the codebase sweep.

What's the best way to consolidate codebase findings into a recommended approach for an issue?

The best way to consolidate codebase findings is using Claude synthesis, which audits dependencies, fills gaps, and produces a recommended approach. This ensures your implementation plan starts with clear choices, evidence, and constraints.

Why does issue research prevent overwriting existing artifacts in the tasks directory?

Issue research prevents overwriting existing artifacts to safeguard your workflow history. It ensures prerequisite validation via the tasks/issues.md lookup and writes a bounded output file at tasks/research-issue-$ARGUMENTS.md without destroying previous research.

When do I need diagnostic understanding and decision axes before implementing a board issue?

You need diagnostic understanding and decision axes when an issue requires evidence and constraints before implementation. This applies to issue flows where you must map the solution space, audit dependencies, and establish a recommended approach prior to planning.