h3y6e/spec-research

Research Skill

Purpose

Core principle: Evidence before decisions. No recommendation without tested findings.

Investigate a focused topic and produce specs/{feature}/research/{topic}.md with findings, a decision, and impact assessment. This skill can be invoked independently or from any other skill when deeper investigation is needed.

Input

• Research question or topic from the user
• Existing specs/constitution.md when present
• Existing specs/{feature}/spec.md when present
• Existing specs/{feature}/plan.md when present
• Existing specs/{feature}/research/*.md when present

Output

• specs/{feature}/research/{topic}.md
• Updated specs/{feature}/spec.md when findings change requirements
• Updated specs/{feature}/plan.md when findings change execution design

Steps

1. Resolve language and shared rules from specs/constitution.md when present; otherwise infer from the available workflow documents and the user's own message. Ask only if still unclear, then conduct all subsequent interaction in this language.
2. Clarify the research scope.
   • Identify the feature slug and research topic
   • Frame a clear research question
   • Determine whether existing spec.md or plan.md context is relevant
3. Gather information.
   • Read existing project context (spec.md, plan.md, other research/*.md)
   • Investigate external sources: documentation, APIs, library comparisons, platform constraints
   • Run a proof of concept when hands-on validation is needed — don't trust documentation alone for critical decisions
   • Compare against working examples or reference implementations when a pattern already exists
   • For failures or unexpected behavior, reproduce the symptom and identify root cause before recommending fixes
   • Form a hypothesis, test it minimally, then record what you found. One variable at a time.
4. Create the research file from references/research-template.md.
   • Research Question: one clear question the research answers
   • Context: feature, topic, and scope of investigation
   • Sources: all references consulted
   • Findings: factual observations with evidence
   • Decision: selected option with rationale AND alternatives considered — a decision without rejected alternatives is not a real decision
   • Impact: assessed effect on spec, plan, and tasks
   • Follow-ups: remaining open items, if any
5. Assess impact on existing documents.
   • If findings change requirements or user-visible behavior: flag spec impact
   • If findings change spec-to-spec prerequisites: update spec.md frontmatter dependencies and flag spec impact
   • If findings change execution design, task dependencies, or validation strategy: flag plan impact
   • If no upstream documents exist yet, record impact as guidance for future phases
6. Apply backflow when existing approved documents are affected.
   • Update spec.md and reset its status to draft when findings are spec-impacting
   • Update plan.md and reset its status to draft when findings are plan-impacting
   • Do not apply backflow when upstream documents do not yet exist
7. Perform final review and keep the file within 150 lines.
   • Remove repetition
   • Simplify wording
   • Ensure the decision is clearly stated with rationale
8. In the completion message, suggest the next step.
   • If a spec does not yet exist: spec-specify
   • If a spec exists but no plan: spec-plan
   • If a plan exists and is approved: spec-implement
   • If more research is needed: continue spec-research

Success Criteria

• The research question is clearly stated and answered.
• Findings are backed by evidence or direct observation.
• A decision is recorded with rationale and alternatives.
• Impact on existing spec and plan documents is assessed.
• Backflow is applied when approved documents are affected.

Completion Guidance

• This is a utility skill; the next step depends on workflow context
• Include the research topic, decision summary, and generated file path in the response