Scientific Analysis Architect

If a required specialist is unavailable, stop and inform the user. Do not attempt the specialist work yourself.

Tool Selection

Default to Task tool when in doubt. Self-check: "Am I about to load specialist instructions into my context so I can do their work? If yes, use Task tool instead."

State Anchoring

Start every response with: "[Phase N/7 - {phase_name}] {brief status}"

Before starting any phase (Phase 1 onward): Read {session_dir}/session-state.json. Confirm current_phase and completed_phases match expectations.

After any user interaction: Answer the user, then re-anchor: "Returning to Phase N - {phase_name}. Next step: {action}."

When to Use

• Planning multi-chapter scientific data analysis (RNA-seq, proteomics, imaging)
• Need expert consultation (statistician, mathematician, programmer perspectives)
• Want markdown analysis documents with pseudocode for implementation
• Research project requires 3-7 chapters of analysis

When NOT to Use

• Need actual code implementation (use programming-pm after this skill; provide the generated .md analysis documents as input)
• Need literature review (use lit-pm skill)
• Single analysis without chapter structure
• Already have detailed analysis plan

Workflow Overview

User Request
     |
+----v--------------------+
| Phase 0: Initialization | ~2 min
| Session setup, validation|
| - Output dir validation  |
+----+--------------------+
     |
+----v--------------------+
| Phase 1: Birds-Eye      | ~12 min
| Planning                |
| [research-architect]    |
+----+--------------------+
     |
research-structure.md (3-7 chapters)
     |
+----v--------------------+
| Phase 2: Subsection     | ~12 min
| Planning                |
| [analysis-planner]      |
|   -> 3 consultants      |
+----+--------------------+
     |
chapter{N}-notebook-plans.md
     |
+----v--------------------+
| Phase 3: Structure      | ~5 min
| Review                  |
| [structure-reviewer]    |
+----+--------------------+
     |
[USER APPROVAL GATE 1]
     |
+----v--------------------+
| Phase 4: Plan           | ~10 min
| Review (parallel)       |
| [notebook-reviewer]     |
+----+--------------------+
     |
[USER APPROVAL GATE 2]
     |
+----v--------------------+
| Phase 5: Document       | ~10 min
| Generation              |
| Step 1: Master overview |
| Step 2: Analysis docs   |
| [orchestrator + notebook-generator]
+----+--------------------+
     |
.md files with pseudocode +
analysis-strategy-overview.md
     |
+----v--------------------+
| Phase 6: Statistical    | ~10-20 min
| Fact-Checking           |
| [statistical-fact-checker]
| INTERVIEW MODE          |
+----+--------------------+
     |
Corrected analysis docs (final)
+ Refreshed overview (if corrections applied)
     |
+----v--------------------+
| Phase 7: Audience        | ~5 min
| Document Generation      |
| [orchestrator]           |
+----+--------------------+
     |
researcher-plan.md +
.research-architecture/
  architect-handoff.md +
  engineering-translation.md

Estimated Runtime: 61-81 minutes for 3 chapters

Phase 0: Initialization

Owner: Orchestrator Duration: 2-5 minutes Checkpoint: Never (automatic)

1. Create session directory:

   • Primary: {output_directory}/.scientific-analysis-session/
   • Fallback: /tmp/scientific-analysis-architect-session-{YYYYMMDD}-{HHMMSS}-{PID}/

2. Validate output directory:

   • Check exists and writable
   • Perform write test
   • If fails, offer alternatives

3. Initialize session state:

   • Create session-state.json
   • Set status: "initialized"

4. Archival Compliance Check: After session setup, follow the archival compliance check pattern: a. Read the reference document: ~/.claude/skills/archive-workflow/references/archival-compliance-check.md b. If file not found, use graceful degradation (log warning, proceed without archival check) c. Apply the 5-step pattern to all file creation operations

   • Store guidelines in session state (session-state.json)
   • When creating analysis documents and analysis directories, validate proposed paths against archival conventions
   • Pass archival_context to all downstream agent dispatches

Quality Gate 0: Session directory created, output directory validated.

Phase Transition: Phase 0 complete -> Announce to user -> PROCEED to Phase 1: Birds-Eye Planning

Phase 1: Birds-Eye Planning

If resuming from a previous session: Read {session_dir}/session-state.json to confirm Phase 0 is complete.

Owner: research-architect (Sonnet 4.6) Duration: ~12 minutes Timeout: 15 minutes

1. Ask user: "Please describe your dataset and research goals"
2. If uncertainty detected ("not sure", "maybe"):
   • Fan-out to analysis-brainstormer and method-brainstormer (Haiku 4.5)
   • Present brainstorming suggestions
3. Generate research-structure.md with 3-7 chapters

Biology-Agnostic Behavior:

• Agents ASK: "What biological questions are you trying to answer?"
• Agents DO NOT inject: "You should look at cell types"

Output: {session_dir}/research-structure.md

Quality Gate 1: Structure has 3-7 chapters, each with goal and analyses.

Phase Transition: Phase 1 complete -> Announce to user -> PROCEED to Phase 2: Subsection Planning

Phase 2: Subsection Planning

Before starting Phase 2: Read {session_dir}/session-state.json. Confirm Phases 0-1 are complete.

Owner: analysis-planner (Sonnet 4.6) Duration: ~12 minutes for 3 chapters Timeout: 20 minutes total

For each chapter:

1. Fan-out to expert panel (parallel, all Haiku):

   • statistician-consultant: Statistical approach validation
   • mathematician-consultant: Algorithm requirements
   • programmer-consultant: Data requirements

2. Fan-in: Aggregate recommendations

3. If consultants disagree, present conflict to user

4. Generate chapter{N}-notebook-plans.md

Consolidated Escalation (if parallel failures):

• Wait for all retries before escalating
• Single prompt with all failures
• Statistician is critical; others are optional

Output: {session_dir}/chapter{N}-notebook-plans.md (one per chapter)

Quality Gate 2: All chapters have analysis plans, no unresolved conflicts.

Phase Transition: Phase 2 complete -> Announce to user -> PROCEED to Phase 3: Structure Review

Phase 3: Structure Review

Before starting Phase 3: Read {session_dir}/session-state.json. Confirm Phases 0-2 are complete.

Owner: structure-reviewer (Haiku) Duration: ~5 minutes Timeout: 10 minutes

1. Review research-structure.md and all chapter plans
2. Check for missing dependencies, redundancies, logical issues
3. Generate structure-review-report.md

Output: {session_dir}/structure-review-report.md

USER APPROVAL GATE 1:

Structure Review Complete

Summary:
- {N} chapters planned
- {M} analyses total
- {K} issues identified

Approve / Request changes / Reject? [A/c/r]

Phase Transition: Phase 3 complete (user approved) -> PROCEED to Phase 4: Plan Review

Phase 4: Plan Review

Before starting Phase 4: Read {session_dir}/session-state.json. Confirm Phases 0-3 are complete.

Owner: notebook-reviewer (Sonnet 4.6) Duration: ~10 minutes Timeout: 15 minutes total

1. Fan-out: One reviewer per chapter (parallel)
2. Check pseudocode completeness, statistical correctness, data flow
3. Fan-in: Aggregate review reports

Output: {session_dir}/notebook-review-report.md

USER APPROVAL GATE 2:

Plan Review Complete

Per-Chapter Summary:
- Chapter 1: {N} analyses, {K} issues
...

Approve / Request changes / Reject? [A/c/r]

Phase Transition: Phase 4 complete (user approved) -> PROCEED to Phase 5: Document Generation

Phase 5: Document Generation

Before starting Phase 5: Read {session_dir}/session-state.json. Confirm Phases 0-4 are complete.

Owner: Orchestrator (Step 1) + notebook-generator (Step 2) Duration: ~10 minutes Timeout: 20 minutes total

Step 1: Generate Master Strategy Overview (Orchestrator-owned)

Synthesize the approved research structure and chapter plans into a single overview document:

• Read research-structure.md and all chapter{N}-notebook-plans.md files
• Generate analysis-strategy-overview.md containing:
  • Project objective (from research structure)
  • Dataset summary
  • Strategy at a Glance table (chapter, title, goal, analyses, key method)
  • Chapter summaries (2-4 sentences each)
  • Data flow between chapters (text-based diagram)
  • Consolidated methods table (unique methods with justification)
  • Required libraries
  • Execution order with dependency notes
  • Assumptions and limitations
• Write to both {output_dir}/analysis-strategy-overview.md and {session_dir}/analysis-strategy-overview.md

This document synthesizes already-approved content. It does NOT introduce new analyses or methods.

Template guidelines:

• Total length: 1-3 pages (concise, not comprehensive)
• Chapter summaries: 2-4 sentences each (what and why, not how)
• For projects with <= 4 chapters: omit Execution Order if linear
• For projects with >= 6 chapters: include a dependency graph

Step 2: Generate Analysis Documents (notebook-generator)

1. Fan-out: One generator per chapter (parallel)
2. Create .md files with hybrid prose + fenced pseudocode blocks
3. Each analysis document follows this structure:
   • ## Goal: What this analysis achieves
   • ## Statistical Approach: Method, justification, assumptions, corrections
   • ## Prerequisites: Input data, required libraries, upstream dependencies
   • ## Analysis Steps: Numbered steps with prose + fenced Python pseudocode blocks
   • ## Expected Outputs: Output files/objects, format, characteristics
   • ## Notes and Caveats: Assumptions, limitations, alternatives
4. Write to both output directory and session directory (backup)
5. Fan-in: Verify all documents created

Code Block Formatting Rules:

• Use triple backticks with python language identifier
• Never nest fenced code blocks
• If pseudocode contains triple-quoted strings (docstrings), use single-quoted triple quotes inside comments
• For multi-line string literals, use comment notation instead

Partial Completion Handling:

• If some chapters fail, offer to proceed with available
• Enable per-chapter regeneration later

Output:

• {output_dir}/chapter{N}_{slug}/analysis{N}_{M}_{slug}.md
• {output_dir}/analysis-strategy-overview.md
• {session_dir}/analyses/ (backup)
• {session_dir}/analysis-strategy-overview.md (backup)

Quality Gate 5: All analysis documents have required sections (Goal, Statistical Approach, Analysis Steps, Expected Outputs), at least one fenced code block each, balanced code fences. Master strategy overview exists with required sections.

Phase Transition: Phase 5 complete -> Quality Gate 5 -> PROCEED to Phase 6: Statistical Fact-Checking

Phase 6: Statistical Fact-Checking

Before starting Phase 6: Read {session_dir}/session-state.json. Confirm Phases 0-5 are complete.

Owner: statistical-fact-checker (Sonnet 4.6) Duration: ~10-20 minutes Timeout: 30 minutes

INTERVIEW MODE:

If <= 5 concerns: Present one at a time If > 5 concerns: Present summary first, offer batch options

Concern Format:

Statistical Concern {N} of {total}

Document: {document_path}
Section: {section_path}
Code Block: {code_block_index}
Severity: {severity}

Issue: {description}

Current: {current_content}
Recommendation: {recommended_fix}

Accept? [yes/no/skip/explain]

Section paths use hierarchical notation: "Analysis Steps > Step 3: Normalization" to disambiguate duplicate headings.

Batch Options (after 5 concerns):

• Continue one-by-one
• Accept all remaining
• Reject all remaining
• Accept critical/standard, skip minor

After Interview:

Summary:
- {X} accepted, {Y} rejected, {Z} skipped

Apply corrections? [yes/no]

Post-Phase 6 Refresh: If any corrections were applied during the interview, regenerate the master strategy overview document (analysis-strategy-overview.md) to reflect corrected methods and approaches. The orchestrator performs this refresh since it synthesizes already-corrected content. Re-validate the overview against Gate 5 criteria.

Output:

• {session_dir}/statistical-review-report.md
• {session_dir}/corrections-manifest.json
• Updated .md analysis documents (if corrections applied)
• Refreshed analysis-strategy-overview.md (if corrections applied)

Post-Workflow: Git Strategy Advisory (Optional)

After Phase 6 completes and all analysis documents are finalized, you MAY invoke git-strategy-advisor via Task tool in post-work mode to recommend how to handle the generated files in version control:

Invocation (via Task tool):

Use git-strategy-advisor to determine git strategy for completed work.