skillpanel/maister/research

Research Orchestrator

Systematic research workflow from question definition to evidence-based documentation.

Initialization

BEFORE executing any phase, you MUST complete these steps:

Step 0: Session-reminder conflict resolution (decide ONCE)

Before doing anything else, settle this policy now and do not re-litigate it at any gate:

`→ MANDATORY GATE` markers fire regardless of session-reminders, permission mode, or prior approval patterns. Auto / acceptEdits / bypassPermissions modes, reminders saying "work without stopping" / "continue without asking" / "minimize clarifying questions," and compaction summaries showing the user approving every prior gate do NOT exempt you from invoking AskUserQuestion at a gate. They apply only to your discretionary clarifications.

If you find yourself reasoning "the user has been approving everything, so I can skip this gate" or "auto-mode is on, so I should minimize questions" — that reasoning IS the failure mode. STOP and fire the gate.

Full framework rule: ../orchestrator-framework/references/orchestrator-patterns.md § 2 and § 2.1.

Step 1: Load Framework Patterns

Read the framework reference file NOW using the Read tool:

1. ../orchestrator-framework/references/orchestrator-patterns.md - Delegation rules, interactive mode, state schema, initialization, context passing, issue resolution

Step 2: Initialize Workflow

1. Capture the clock: run date -u +"%Y-%m-%dT%H:%M:%SZ" via Bash NOW — you do NOT know the time from context. Every timestamp written this turn (created, updated, generated, phases[].started) uses this value. Date-only or T00:00:00Z values are the documented failure mode (orchestrator-patterns.md § 4 Timestamp Rule). Re-run date in later turns before writing timestamps.
2. Create Task Items: Use TaskCreate for all phases (see Phase Configuration), then set dependencies with TaskUpdate addBlockedBy
3. Create Task Directory: .maister/tasks/research/YYYY-MM-DD-task-name/
4. Initialize State: Create orchestrator-state.yml with research context
5. Set up Operator Dashboard (orchestrator-patterns.md § 8) — first read .maister/config.yml and set orchestrator.options.html_output (default true if the file/key is absent). When `html_output` is false, SKIP this entire step — no dashboard.html, no dashboard-data.js, no browser auto-open — and proceed. Otherwise: copy ../orchestrator-framework/assets/dashboard.html to the task root as dashboard.html, write the initial dashboard-data.js (all phases pending, task.type: "research"), then auto-open it in the user's browser (open / xdg-open / start per platform, passing the plain absolute filesystem path — NEVER a hand-built file:// URL; on failure just print the path — never block). On resume: re-copy dashboard.html only if missing; regenerate dashboard-data.js from state; then auto-open it in the browser again (same opener as a new task — the OS focuses an already-open tab rather than duplicating).

Output:

🚀 Research Orchestrator Started
 
Task: [research question]
Directory: [task-path]
Dashboard: open [task-path]/dashboard.html in a browser to monitor progress
 
Starting Phase 1: Initialize research...

Operator Visibility (applies to every phase)

Config gate: these rules assume options.html_output is true (read from .maister/config.yml at init, default true). When false: skip the Dashboard-upkeep rule entirely (no dashboard files, no browser open, no rewrites) and the HTML-companions rule (do NOT pass html_style_guide_path; subagents write md only). The Artifact Summary Contract (§ 7 TL;DR blocks) and phase_summaries in state stay active either way.

Cross-cutting rules from orchestrator-patterns.md (same as the development orchestrator):

1. Artifact Summary Contract (§ 7): every artifact-writing subagent prompt MUST include the contract instruction (artifacts open with TL;DR / Key Decisions / Open Questions / Risks (the writer heading is ## Open Questions / Risks)). At context extraction, lift decisions, risks, and artifacts into phase_summaries.[phase] — verbatim, never re-summarized.
2. Dashboard upkeep (§ 8): rewrite dashboard-data.js at every phase START (mark in_progress before delegating), BEFORE firing every exit gate (register the finished phase's artifacts/summary/decisions/risks — the operator reviews them on the dashboard while answering; status stays in_progress until the gate passes), after every phase completion (including skipped phases 3-5, with reason), every gate decision, and at finalization. Phase 1 addition: also refresh after each of its 4 steps completes, registering that step's artifacts — Phase 1 is long and the operator should see brief → plan → findings → report appear incrementally. In particular, after Step 4 the report (outputs/research-report.md + .html) MUST be registered before the Phase 1 exit gate fires.
3. HTML companions (§ 9): pass html_style_guide_path (absolute path to ../orchestrator-framework/references/html-report-style.md) to research-synthesizer, solution-brainstormer, and solution-designer. Register returned companion paths in phase_summaries.[phase].artifacts[].html so the dashboard hero cards link HTML first.
4. icon_hint values per phase: 1 analysis, 2 plan, 3 spec, 4 plan, 5 spec, 6 done.
5. State writes (§ 4 Write Rule): update orchestrator-state.yml key by key in place, validate it with a re-read after every write, and stop with AskUserQuestion on a malformed file — never continue on a state file the operator tooling cannot read.

When to Use

Use when:

• Need comprehensive research on a topic
• Exploring codebase patterns or architecture
• Gathering requirements or best practices
• Want systematic evidence-based answers
• Research will feed into development workflows

DO NOT use for: Development tasks, bug fixes, performance optimization.

Core Principles

1. Evidence-Based: Every finding must have source citation
2. Systematic: Follow structured methodology for consistent results
3. Multi-Source: Gather from codebase, docs, config, external sources
4. Synthesized: Cross-reference findings, identify patterns
5. Actionable: Produce outputs that enable next steps

Local References

Phase Configuration

Research Types

Workflow Phases

Phase 1: Research Foundation

Purpose: Initialize research, plan methodology, gather information from all sources, and synthesize findings into a research report Execute: Multi-step: Direct + research-planner + information-gatherer (xN) + research-synthesizer Output: planning/research-brief.md, planning/research-plan.md, planning/sources.md, analysis/findings/*.md, analysis/synthesis.md, outputs/research-report.md State: Set research_context.research_type, research_question, scope, methodology, sources, confidence_level, gathering_strategy

This phase executes 4 sequential steps. On resume, check existing artifacts to skip completed steps.

Step 1: Initialize (Direct)

Artifacts: planning/research-brief.md Resume check: If planning/research-brief.md exists, skip to Step 2

1. Parse research question (from command or prompt user)
2. Classify research type (auto-detect from keywords or use --type flag)
3. Determine scope (included, excluded, constraints)
4. Define success criteria
5. Create research brief
6. Update state: set research_context.research_type, research_question, scope
7. Discover project documentation: Read .maister/docs/INDEX.md (if exists), extract ALL file paths from the "Project Documentation" section — includes predefined docs AND any user-added project docs. Store as research_context.project_doc_paths in state.

Step 2: Plan (Subagent)

Artifacts: planning/research-plan.md, planning/sources.md Resume check: If planning/research-plan.md AND planning/sources.md exist, skip to Step 3

INVOKE NOW: Use Task tool with subagent_type: maister:research-planner

Context to pass: task_path, research_brief_path, research_type, research_question, scope, project_doc_paths (from state), methodology_reference (absolute path to references/research-methodologies.md)

Update state: research_context.methodology, sources

Step 3: Gather + Merge (Parallel Subagents + Direct)

Artifacts: analysis/findings/*.md (category-specific) Resume check: If any analysis/findings/*.md files exist, skip to Step 4

Determine gatherer count and categories:

1. Read planning/research-plan.md for Gathering Strategy section
2. If gathering strategy found: use specified categories and count (cap at 8 max)
3. If no gathering strategy: fall back to default 4 categories (codebase, documentation, configuration, external)
4. Update state: research_context.gathering_strategy

CRITICAL: Launch all N agents in ONE message for parallel execution.

Parallel Execution Pattern:

Read gathering strategy from research-plan.md
For each category in strategy:
  Use Task tool: source_category=[category_id] → analysis/findings/[prefix]-*.md

Step 4: Synthesize (Subagent)

Artifacts: analysis/synthesis.md, outputs/research-report.md Resume check: If analysis/synthesis.md AND outputs/research-report.md exist, skip (Phase 1 complete)

INVOKE NOW: Use Task tool with subagent_type: maister:research-synthesizer

Context to pass: task_path, findings_directory_path, research_question, research_type, methodology, html_style_guide_path (for the research-report.html companion)

Synthesizer produces:

• Pattern analysis and cross-references (analysis/synthesis.md)
• Comprehensive research report answering research question (outputs/research-report.md)
• Confidence levels for each finding
• Documented gaps and uncertainties

Update state: research_context.confidence_level