brain-investigate

name	brain-investigate
description	Deep multi-source investigation for architecture research and cross-team context gathering. Use when the user says "investigate", "deep dive", "research", "what do we know about", "how does X work", "gather context on", or "find out about". Also triggers on Jira issue IDs when paired with investigation intent.

Brain Investigate

Run a structured investigation across available sources, produce a report, and update the relevant project.

Phase 1: Scope

1. Parse the user's request into a clear investigation topic and 2-3 sub-questions to answer.
2. If a Jira issue ID is provided, fetch it first:
   • jira_read_api_call with endpoint issues.get, params {"issue_id": "<ID>"}.
   • Use the issue title, description, comments, and linked issues as seed context.
3. List project folders in projects/ and read their overview.md frontmatter to identify the related project(s).
4. Read the project's overview.md to understand current documented state.
5. Ask the user which sources to search if ambiguous. Default to all available.
6. Ask the user for any local code repository paths relevant to the investigation.

Phase 2: Gather

Search sources in parallel. Launch up to 4 subagents concurrently for independent searches.

Always search the brain first — prior investigations, journal entries, and task notes may already contain relevant context.

Brain (prior context)

Search the second brain's semantic index for existing reports, journal entries, and task notes.

CallMcpTool: user-brain / search
  query: "<topic>"
  top_k: 10

Review results for prior investigations, related journal entries, and existing task notes. This avoids duplicating past work and provides a foundation for the new investigation. If a relevant report already exists, read it in full and build on it rather than starting from scratch.

Slack

Search for discussions, decisions, and context.

CallMcpTool: user-slack / slack_read_api_call
  endpoint: search.messages
  params: {"query": "<topic> in:#<relevant-channel>"}
  analysis_prompt: "Summarize the key decisions and context about <topic>"

Refine with date ranges or channels if initial results are noisy.

Jira

Find related tickets, epics, and linked design docs.

CallMcpTool: user-jira / jira_read_api_call
  endpoint: issues.search
  params: {"jql": "text ~ \"<topic>\" ORDER BY updated DESC", "maxResults": 20}

For each relevant issue, fetch full details with issues.get to read descriptions and comments.

Confluence

Find design docs, RFCs, and architecture pages.

CallMcpTool: user-confluence / search_confluence_pages
  query: "text ~ \"<topic>\""
  limit: 10

For promising results, fetch full content:

CallMcpTool: user-confluence / get_confluence_page_content
  page_id: <id>

Google Docs

Find shared docs and meeting notes.

CallMcpTool: user-google / google_read_api_call
  endpoint_or_operation: search
  params: {"query": "<topic>"}

For relevant results, fetch document content with endpoint docs/documents.

Glean

Broad enterprise search when other sources don't cover it, or as a first pass.

CallMcpTool: user-glean / glean_read_api_call
  endpoint: search.query
  params: {"query": "<topic>"}

Local Code

If the user provided repo paths, search them:

• Use SemanticSearch for conceptual questions ("how does X work?")
• Use Grep for specific symbols, config keys, or error messages

Source Attribution

For every finding, record:

• Source type (Slack, Jira, Confluence, Google, Code)
• Identifier (channel + timestamp, issue key, page title, file path + line)
• Date of the information
• Summary of what was found

Phase 3: Synthesize

1. Organize findings by sub-question.
2. For each sub-question, write a concise answer supported by the gathered evidence.
3. Call out:
   • Gaps — sub-questions that couldn't be answered
   • Contradictions — conflicting information across sources (note which source is likely more current)
   • Stale info — findings that may be outdated based on dates
4. Draft a structured report following the template.
5. Present the draft to the user for review before persisting.

Phase 4: Persist

After user confirms the report:

1. Save the report to reports/YYYY-MM-DD-<slug>.md using templates/report.md.

   • <slug> is a kebab-case summary of the topic.
   • Fill in frontmatter: date, project, jira (if applicable), tags.
   • Populate all sections: Question, Sources Consulted, Findings, Open Questions, Links.

2. Update the project overview — propose specific additions to the project's overview.md:

   • New architectural understanding → Architecture section
   • Status updates → Status or Current Workstreams section
   • Ask the user to confirm each proposed update before writing.

3. Link from today's journal — append a reference to today's journal/daily/YYYY-MM-DD.md:

   - Completed investigation: [[reports/YYYY-MM-DD-<slug>|<title>]]
   

4. Git commit — stage only the changed files and commit:

   report: <slug>
   

Edge Cases

• If a source returns no results, note it in Sources Consulted as "searched, no results".
• If the user doesn't provide a Jira ID or project, still run the investigation — just skip the Jira seed step and ask the user to confirm which project to file under.
• If the investigation spans multiple projects, list all in the frontmatter tags and update each project's overview.
• If the user wants to continue or expand an existing report, read the existing report first and append new findings rather than creating a duplicate.