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 at one of the two tracked research roots:
- Feature-associated research:
docs/features/<feature>/research/<timestamp>-<short-name>-research.md(for exampledocs/features/active/<feature>/research/<timestamp>-<short-name>-research.md). - One-off research not tied to a feature:
docs/research/<timestamp>-<short-name>-research.md. - Routing rule: write to the feature research root when an active feature folder is in scope (the orchestrator supplies the resolved path from
feature-folderinorchestrator-state.json); otherwise write todocs/research/. The filename convention<timestamp>-<short-name>-research.mdis unchanged. - 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.
- For every numeric count, enumeration, or population proposed for an approved
spec.mdacceptance criterion, add complete## Numeric Derivation Evidence. Each record must identifyComplete Family,Exhaustive Search Scope,Inclusion Rules,Exclusion Rules,Primary Search Strategy or Query Expression,Primary Member Set,Primary Count,Cross-check Search Strategy or Query Expression,Cross-check Member Set,Cross-check Count, andMember-set Comparison. - Both derivations must be non-empty and independently constructed. They must use distinct search strategies or query expressions, independently enumerate the member sets, and explicitly compare normalized member sets. The scope must cover the entire declared family, including all relevant overloads and members; reject a single grep, a narrow named-pattern search, or a query that covers only one family member even when totals and member sets appear equal. Withhold the numeric assertion if the records are incomplete, duplicated, non-exhaustive, narrow, or disagree.
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 researcher SubagentStop hook blocks feature research without a complete section. 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.
- Omit numeric acceptance-criterion facts when the numeric derivation record is absent, incomplete, or disagrees.