Research Issue Skill
Research the best implementation approach for a feature or bug described in the provided issue and spec documents. Output is a structured research file, not implementation code.
Inputs
Accept one or more feature documents as context:
docs/features/active/<feature>/issue.md(primary)docs/features/active/<feature>/user-story.md(when present)docs/features/active/<feature>/spec.md(when present)
Output
Create or update a single research file in the applicable tracked research root:
- Feature-associated path:
docs/features/<feature>/research/<timestamp>-<short-name>-research.md - One-off path:
docs/research/<timestamp>-<short-name>-research.md - Use the Task Researcher template from the repository exactly.
- Place rejected-alternatives summaries inside
## Recommended Approach, not as a separate top-level header.
Investigation Areas
1. Current State Analysis
- Identify implementation targets from the feature docs.
- Read relevant modules end-to-end.
- Document current behavior, key abstractions, extension points, and toolchain constraints.
2. Candidate Implementation Approaches
- Research and compare at least two viable approaches.
- Select one final recommendation with justification.
- For any new dependency, confirm whether it already exists in the repo and justify adding it.
- Gather authoritative external documentation to support the recommendation.
3. Behavior Semantics and Edge Cases
- Extract intended behavior from feature docs.
- Define success/failure conditions, ordering rules, cancellation behavior, and CI vs. local expectations.
- Research comparable tools that implement similar semantics.
4. Requirements Mapping to Design
- Map acceptance criteria into a concrete design.
- Propose state model, transitions, internal API boundaries, and required file changes.
5. Testing Implications
- Propose a test strategy consistent with repository policy (unit tests for pure logic, integration seams).
- Do not write test code; describe the strategy only.
6. Pre-Mortem
- Feature-associated research (a research path under
docs/features/) MUST carry a## Pre-Mortemsection with one bullet beginning with each of the seven labelsReview checklists,Coverage,Mirror parity,File size,Test isolation,CI-only behavior, andEvidence. Each bullet states how the next review or CI run could fail on that dimension and the mitigation the plan must carry; a label that does not apply is written as "not applicable" followed by the reason. - One-off research under
docs/research/is exempt. - The
execution-environmentskill states the CI shape, contract tests, and isolation checks the section accounts for.
Constraints
- Research only. Do not implement changes.
- Ground all findings in verified evidence from the codebase and authoritative external sources.
- Keep discussion of non-selected approaches brief.
- Do not claim or perform nested worker delegation.