create-investigation

Create Investigation Document

Create a structured investigation document from a rough, conversational idea or question.

Raw input to process: The user's freeform thoughts following this command

Your workflow:

1. Parse and understand the raw input

   • The input may be:
     • Voice-to-text transcription (conversational, with verbal fillers)
     • Rough notes or bullet points
     • Stream-of-consciousness thinking
     • Semi-structured but incomplete thoughts
   • Extract the core question or problem being explored
   • Identify key concerns, unknowns, or motivations mentioned

2. Identify the investigation scope

   • What is the central question? ("Should we...?", "Is it worth...?", "Could we...?")
   • What type of investigation is this?
     • Code quality/refactoring question
     • Technology evaluation
     • Feature feasibility study
     • Performance concern
     • Architecture decision exploration
   • What's the uncertainty level? (early exploration vs. focused research)

3. Search for relevant context

   • Look for existing code, docs, or patterns related to the topic
   • Identify similar features or systems already implemented
   • Find related proposals, architecture docs, or sessions
   • Gather baseline information to inform the investigation

4. Structure the investigation

   • Question/Motivation: Clarify the core question and why it matters
   • Current State Analysis: Document what exists today (code, systems, patterns)
   • Initial Observations: Capture any early insights from context search
   • Open Questions: List specific things to investigate further
   • Keep it flexible - use sections that help communicate, skip what doesn't add value

5. Create the investigation document

   • Choose an appropriate filename: YYYY-MM-DD-topic-investigation.md
   • Write to docs/investigations/[filename].md
   • Set Status: "Active" (investigation is starting, not concluded)
   • Set Outcome: "In Progress"
   • Use investigation template as scaffolding, not a mandatory form
   • Include relevant sections:
     • Question/Motivation (from parsed input)
     • Current State Analysis (from context search)
     • Investigation Findings (what you've discovered so far)
     • Open Questions (specific things to explore)
     • Next Steps (immediate actions to continue investigation)
   • Remember: lightweight to moderate complexity - avoid time estimates, use complexity indicators

6. Transform the input thoughtfully

   • Preserve intent: Keep the user's core concerns and questions
   • Add structure: Organize scattered thoughts into logical sections
   • Remove noise: Filter out verbal fillers ("um", "you know", "like") from voice input
   • Add context: Include relevant code references or existing patterns discovered
   • Stay open-ended: Don't jump to conclusions - frame as exploration, not answers
   • Maintain uncertainty: If the user is unsure, the investigation should reflect that

Important guidelines:

• This is a starting point, not a conclusion: The investigation document should frame the research, not answer it
• Don't over-formalize: The user's rough thoughts should become structured but remain exploratory
• Leave room for discovery: Include "Open Questions" and "Research Plan" sections
• Link to context: Reference any relevant existing code, docs, or patterns found
• Scope reminder: Note that investigation should be lightweight to moderate complexity with clear boundaries
• Conversational to professional: Transform speech patterns into clear written prose, but keep the exploratory tone

Handling different input styles:

Voice-to-text input:

"Um, so I've been thinking, you know, like maybe we should look at refactoring
the AI composables because they're getting kind of messy and there's a lot of
duplication, like every time we add a new workflow it's basically copy-paste,
and I'm not sure if that's, like, a real problem or just me being picky..."

Transform to:

## Question / Motivation

Should we refactor the AI composables? There appears to be significant code
duplication across workflows, with each new workflow requiring substantial
copy-paste. Need to determine if this is a genuine maintainability concern or
acceptable given current system complexity.

Rough notes input:

- ai composables getting complex
- lots of duplication?
- every new workflow = 200+ lines boilerplate
- maybe factor pattern?
- not sure if worth it

Transform to:

## Question / Motivation

Should we refactor AI composables to reduce duplication? Initial observation
suggests each new workflow requires ~200+ lines of boilerplate code.
Investigating whether a factory pattern or similar abstraction would provide
value vs. current implementation.

## Open Questions

- How much actual duplication exists across composables?
- What patterns could reduce boilerplate?
- What's the maintenance cost of current approach vs. refactored approach?

Output:

Create an investigation document in docs/investigations/ with:

• Appropriate filename based on topic and current date
• Status: "Active"
• Structured format following investigations README template
• Clear research plan for continuing the investigation
• Referenced context from codebase/docs

Inform the user of:

• The chosen filename and location
• The core question extracted from their input
• Key areas identified for investigation
• Suggested next steps for continuing the research
• Any relevant existing code or docs that should be reviewed