owflow 0.1.1 → 0.1.3

package/dist/skills/research/SKILL.md

@@ -0,0 +1,493 @@
+---
+name: research
+description: Orchestrates comprehensive research workflows from question definition through findings documentation. Handles technical, requirements, literature, and mixed research types with adaptive methodology, multi-source gathering, pattern synthesis, and evidence-based reporting. Supports standalone research tasks and embedded research phase in other workflows.
+user-invocable: true
+---
+
+# Research Orchestrator
+
+Systematic research workflow from question definition to evidence-based documentation.
+
+## Initialization
+
+**BEFORE executing any phase, you MUST complete these steps:**
+
+### 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. **Create Task Items**: Use `TaskCreate` for all phases (see Phase Configuration), then set dependencies with `TaskUpdate addBlockedBy`
+2. **Create Task Directory**: `.owflow/tasks/research/YYYY-MM-DD-task-name/`
+3. **Initialize State**: Create `orchestrator-state.yml` with research context
+
+**Output**:
+
+```
+🚀 Research Orchestrator Started
+
+Task: [research question]
+Directory: [task-path]
+
+Starting Phase 1: Initialize research...
+```
+
+---
+
+## 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
+
+| File                                     | When to Use | Purpose                                                                                        |
+| ---------------------------------------- | ----------- | ---------------------------------------------------------------------------------------------- |
+| `references/research-methodologies.md`   | Phase 1     | Research type classification, methodology selection, gathering strategies, analysis frameworks |
+| `references/brainstorming-techniques.md` | Phase 3     | Divergent/convergent thinking, interactive exploration, scope guardrails                       |
+| `references/design-techniques.md`        | Phase 5     | Decision documentation (MADR), ADR guidance, decision linking                                  |
+
+---
+
+## Phase Configuration
+
+| Phase | content                                                | activeForm                              | Agent/Skill                                                                  |
+| ----- | ------------------------------------------------------ | --------------------------------------- | ---------------------------------------------------------------------------- |
+| 1     | "Research foundation (init, plan, gather, synthesize)" | "Executing research foundation"         | Direct + research-planner + information-gatherer (xN) + research-synthesizer |
+| 2     | "Evaluate brainstorming value"                         | "Evaluating brainstorming value"        | Direct                                                                       |
+| 3     | "Generate solution alternatives"                       | "Generating solution alternatives"      | solution-brainstormer                                                        |
+| 4     | "Evaluate brainstorming alternatives"                  | "Evaluating brainstorming alternatives" | Direct (interactive)                                                         |
+| 5     | "Design high-level architecture"                       | "Designing high-level architecture"     | Direct + solution-designer                                                   |
+| 6     | "Summarize research and suggest next steps"            | "Completing research"                   | Direct                                                                       |
+
+---
+
+## Research Types
+
+| Type             | Keywords                                 | Focus                       | Typical Outputs                   |
+| ---------------- | ---------------------------------------- | --------------------------- | --------------------------------- |
+| **Technical**    | "how does", "where is", "implementation" | Codebase analysis           | Knowledge base, architecture docs |
+| **Requirements** | "what are requirements", "user needs"    | User/business needs         | Specifications, requirements doc  |
+| **Literature**   | "best practices", "industry standards"   | External research           | Recommendations, comparisons      |
+| **Mixed**        | Multiple keywords, broad questions       | Comprehensive investigation | All output 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 `.owflow/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
+
+**Read `references/research-methodologies.md` NOW using the Read tool** — research type classification, methodology selection, gathering strategies
+
+**INVOKE NOW**: Use Task tool with `subagent_type: research-planner`
+
+**Context to pass**: task_path, research_brief_path, research_type, research_question, scope, project_doc_paths (from state)
+
+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: research-synthesizer`
+
+**Context to pass**: task_path, findings_directory_path, research_question, research_type, methodology
+
+**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`
+
+---
+
+→ Pause
+
+question - "Research foundation complete (initialized, planned, gathered, synthesized). Continue to brainstorming evaluation?"
+
+---
+
+### Phase 2: Optional Phases Decision
+
+> **Phase gate**: Requires `question` confirmation from Phase 1 before executing.
+
+**Purpose**: Evaluate whether brainstorming and/or design phases would be valuable (independently)
+**Execute**: Direct
+**Output**: Updated `orchestrator-state.yml`
+**State**: Set `options.brainstorming_enabled`, `options.design_enabled`
+
+**Auto-resolve if**: `--brainstorm`/`--no-brainstorm` flags (brainstorming only), `--design`/`--no-design` flags (design only)
+
+**Process**:
+
+1. Read `analysis/synthesis.md` summary and `research_type` from state
+2. Evaluate brainstorming value based on:
+   - Number of viable approaches identified in synthesis (multiple → valuable)
+   - Problem novelty (new domain → valuable; well-understood → less so)
+   - Whether synthesis identified competing trade-offs (yes → valuable)
+3. Evaluate design value based on:
+   - Whether research suggests architectural decisions (yes → valuable)
+   - Research type (requirements/mixed → likely valuable; technical → depends)
+   - Whether design artifacts would feed into development workflow
+4. If `brainstorming_enabled` not already set by flag, question:
+   - "[Brainstorming recommendation]. Would you like to explore solution alternatives?"
+   - Options: "Yes, explore alternatives" / "No, skip brainstorming"
+5. If `design_enabled` not already set by flag, question:
+   - "[Design recommendation]. Would you like to generate a high-level design?"
+   - Options: "Yes, generate design" / "No, skip design"
+6. Update state: set `brainstorming_enabled` and `design_enabled`
+
+→ If brainstorming enabled: continue to Phase 3
+→ If brainstorming disabled AND design enabled: skip to Phase 5
+→ If both disabled: skip to Phase 6
+
+---
+
+### Phase 3: Solution Generation
+
+**Purpose**: Generate solution alternatives from research evidence using specialized brainstormer subagent
+**Execute**: solution-brainstormer subagent
+**Output**: `outputs/solution-exploration.md`
+**State**: Update `phase_summaries.phase-3`
+
+**Skip if**: `brainstorming_enabled = false` (user chose to skip in Phase 2, or `--no-brainstorm` flag)
+
+**Read `references/brainstorming-techniques.md` NOW using the Read tool** — divergent/convergent thinking techniques, scope guardrails
+
+> **ANTI-PATTERN**: Do NOT generate solution alternatives inline. The solution-brainstormer agent has specialized multi-perspective analysis capabilities.
+
+**INVOKE NOW**: Use Task tool with `subagent_type: solution-brainstormer`
+
+**Context to pass** (Pattern 7):
+
+- `task_path`, `synthesis_path`, `research_report_path`
+- `output_path`: `outputs/solution-exploration.md` — brainstormer MUST write to this exact path
+- Accumulated context: `research_type`, `research_question`, `confidence_level`, `phase_summaries` (Phase 1)
+- `project_doc_paths` (from state)
+
+> **SELF-CHECK**: After Task tool returns, verify `outputs/solution-exploration.md` exists and contains alternatives. If missing: **STOP. Do NOT proceed to Phase 4 or Phase 5.** Re-invoke the brainstormer with corrected context (ensure `output_path` is `outputs/solution-exploration.md`). If second attempt also fails, use question to report the failure and ask whether to retry or skip brainstorming.
+
+→ **AUTO-CONTINUE**
+
+---
+
+### Phase 4: Solution Convergence
+
+**Purpose**: Present brainstorming alternatives to user for decision-making on each decision area
+**Execute**: Direct (interactive)
+**Output**: Updated `orchestrator-state.yml` with chosen approaches
+**State**: Update `phase_summaries.phase-4` with `decision_areas` and `deferred_ideas`
+
+**Skip if**: `brainstorming_enabled = false`
+**Resume check**: If `phase_summaries.phase-4.decision_areas` has entries with `chosen_approach` set, skip already-resolved areas
+
+> **ANTI-PATTERN**: Do NOT present all decision areas in a single summary table and ask one combined "do you agree?" question. Each area MUST get its own detailed presentation and its own question call.
+>
+> **ANTI-PATTERN**: Do NOT show full alternatives/pros/cons for the first area and then shortcut remaining areas to just a recommendation line + question. EVERY area gets the SAME level of detail — all alternatives with descriptions, pros, and cons. No exceptions.
+
+1. Read `outputs/solution-exploration.md`
+2. For each decision area sequentially, output ALL of the following (steps a-d) BEFORE calling question:
+   a. **Area header**: area name and why this decision matters (1-2 sentences of context)
+   b. **Alternatives detail**: For EVERY alternative in this area, show:
+   - Name and description (2-3 sentences)
+   - Pros (bullet list)
+   - Cons (bullet list)
+     c. **Recommendation**: which alternative is recommended and why (1 sentence)
+     d. **question**: this area's alternatives as options (mark recommended with "(Recommended)") + "Need more info" option
+     e. If user picks → record choice, move to next area
+     f. If "Need more info" → present the detailed trade-off analysis for the requested alternative, then re-ask
+
+> **SELF-CHECK before each question**: Did you output the alternatives with pros/cons for THIS area? If you only showed a recommendation line without listing all alternatives and their pros/cons, STOP and output the full detail before asking.
+
+3. After all areas resolved, present a brief summary of the chosen combination
+4. Update state with chosen approaches per decision area
+
+> **GATE CHECK**: Verify that question was called for EACH decision area. If any decision area was skipped for any reason (e.g., output file missing, read failure), STOP and resolve before continuing. Do NOT mark Phase 4 complete without user convergence on all decision areas.
+
+→ Pause
+
+question - "Brainstorming complete. Continue to high-level design?"
+
+---
+
+### Phase 5: High-Level Design
+
+> **Phase gate**: Requires `question` confirmation from the preceding phase before executing.
+
+**Purpose**: Create architecture design from selected solution approach
+**Execute**: Orchestrator-Direct Hybrid
+**Output**: `outputs/high-level-design.md`, `outputs/decision-log.md`
+**State**: Update `phase_summaries.phase-5`
+
+**Skip if**: `design_enabled = false`
+
+**Read `references/design-techniques.md` NOW using the Read tool** — MADR format, ADR guidance, decision documentation patterns
+
+**Part A — Design Direction (Direct)**:
+
+1. If Phase 4 ran: confirm selected approaches from convergence
+2. If Phase 4 was skipped: use research report recommendations as design input
+3. question for any design preferences or constraints (e.g., "Any architectural constraints or preferences?")
+
+**Part B — Design Generation (Subagent)**:
+
+> **ANTI-PATTERN**: Do NOT generate C4 architecture diagrams or ADRs inline. The solution-designer agent has specialized architecture and MADR documentation capabilities.
+
+**INVOKE NOW**: Use Task tool with `subagent_type: solution-designer`
+
+**Context to pass** (Pattern 7):
+
+- `task_path`, `synthesis_path`, `research_report_path`
+- `solution_exploration_path` (only if Phase 3-4 ran)
+- `selected_approach` (from Phase 4 convergence if ran, or from research report recommendations)
+- `design_preferences` (from Part A)
+- Accumulated context: `research_type`, `research_question`, `confidence_level`, `phase_summaries`
+- `project_doc_paths` (from state)
+
+> **SELF-CHECK**: After Task tool returns, verify both `outputs/high-level-design.md` and `outputs/decision-log.md` exist. If missing: **STOP. Do NOT proceed to Part C.** Re-invoke the designer with corrected context. If second attempt also fails, use question to report the failure and ask whether to retry or skip design.
+
+**Part C — Summary (Direct)**: 3. Read `outputs/high-level-design.md` and `outputs/decision-log.md` 4. Present executive summary to user:
+
+- Architecture style and key components
+- Number of architectural decisions recorded
+- Key decision highlights (1 line each)
+- Integration points with existing system (if applicable)
+
+→ Pause
+
+question - "Design complete. Continue to output generation?"
+
+---
+
+### Phase 6: Completion
+
+> **Phase gate**: Requires `question` confirmation from the preceding phase before executing.
+
+**Purpose**: Summarize research results and suggest next steps
+**Execute**: Direct
+**Output**: No new files — summarizes existing outputs
+
+**Process**:
+
+1. Inventory all generated outputs: `outputs/research-report.md` (always), plus conditional: `solution-exploration.md`, `high-level-design.md`, `decision-log.md`
+2. Present executive summary to user:
+   - Key findings and confidence level
+   - Which optional phases ran (brainstorming, design)
+   - Key decision highlights (if brainstorming/design ran)
+3. If design artifacts exist, suggest starting development in a fresh session:
+   ```
+   To start development based on this research, clear context first or start a new session, then run:
+   /development [task-path]
+   ```
+
+→ End of workflow
+
+---
+
+## Domain Context (State Extensions)
+
+Research-specific fields in `orchestrator-state.yml`:
+
+```yaml
+research_context:
+  research_type: "technical" | "requirements" | "literature" | "mixed"
+  research_question: "[user's question]"
+  scope:
+    included: []
+    excluded: []
+    constraints: []
+  methodology: []
+  sources: []
+  confidence_level: "high" | "medium" | "low"
+  gathering_strategy:
+    categories: []       # e.g., ["codebase", "documentation", "external-apis"]
+    count: 4             # number of gatherer instances
+    source: "planner" | "default"  # where strategy came from
+  phase_summaries:
+    phase-1:
+      summary: "..."
+      steps_completed: []  # track which steps completed for resume
+    phase-3:
+      summary: "..."
+    phase-4:
+      summary: "..."
+      decision_areas: []        # list of {area, alternatives_count, chosen_approach}
+      deferred_ideas: []
+    phase-5:
+      summary: "..."
+      architecture_style: null
+      decisions_count: 0
+
+options:
+  brainstorming_enabled: null  # null=not yet decided, set by Phase 2 or --brainstorm/--no-brainstorm flag
+  design_enabled: null          # independent, set by Phase 2 or --design/--no-design flag
+```
+
+---
+
+## Task Structure
+
+```
+.owflow/tasks/research/YYYY-MM-DD-research-name/
+├── orchestrator-state.yml
+├── planning/
+│   ├── research-brief.md           # Phase 1, Step 1
+│   ├── research-plan.md            # Phase 1, Step 2
+│   └── sources.md                  # Phase 1, Step 2
+├── analysis/
+│   ├── findings/
+│   │   ├── codebase-*.md           # Phase 1, Step 3
+│   │   ├── docs-*.md               # Phase 1, Step 3
+│   │   ├── config-*.md             # Phase 1, Step 3
+│   │   ├── external-*.md           # Phase 1, Step 3
+│   │   └── [custom-category]-*.md  # Phase 1, Step 3 (dynamic categories)
+│   └── synthesis.md                # Phase 1, Step 4 (reasoning log)
+├── outputs/
+│   ├── research-report.md          # Phase 1, Step 4 (main deliverable)
+│   ├── solution-exploration.md     # Phase 3 (conditional)
+│   ├── high-level-design.md        # Phase 5 (conditional)
+│   └── decision-log.md             # Phase 5 (conditional)
+```
+
+---
+
+## Auto-Recovery
+
+| Phase      | Max Attempts | Strategy                                                      |
+| ---------- | ------------ | ------------------------------------------------------------- |
+| 1 (Step 1) | 1            | Prompt user for clarification if question unclear             |
+| 1 (Step 2) | 2            | Expand search patterns, use fallback mixed methodology        |
+| 1 (Step 3) | 3            | Retry failed agents only, continue with successful categories |
+| 1 (Step 4) | 2            | Request targeted re-gathering for gaps                        |
+| 2          | 1            | Re-evaluate recommendation if synthesis unclear               |
+| 3          | 2            | Re-invoke solution-brainstormer with adjusted context         |
+| 4          | 1            | Re-read exploration file, re-present decision areas           |
+| 5          | 2            | Re-invoke solution-designer with adjusted context             |
+| 6          | 0            | Summary only                                                  |
+
+---
+
+## Integration with Other Workflows
+
+### As Standalone Research
+
+**Command**: `/research [research-question]`
+**Flow**: Complete all phases, save outputs in task directory
+
+### As Embedded Research Phase
+
+**Invoked by**: development orchestrator, migration orchestrator
+
+**Integration**:
+
+1. Parent orchestrator invokes research skill
+2. Research executes phases 1-5 (skip Phase 6 completion — parent orchestrator handles next steps)
+3. Design outputs fed into parent's specification phase
+4. Research report saved in parent task's `analysis/research/` directory
+
+**Handoff**:
+
+```yaml
+research_outputs:
+  research_report: "[path to outputs/research-report.md]"
+  findings_directory: "[path to analysis/findings/]"
+  solution_exploration: "[path to outputs/solution-exploration.md]"
+  high_level_design: "[path to outputs/high-level-design.md]"
+  decision_log: "[path to outputs/decision-log.md]"
+```
+
+---
+
+## Command Integration
+
+Invoked via:
+
+- `/research [question] [--type=TYPE] [--brainstorm] [--no-brainstorm] [--design] [--no-design]` (new)
+- `/research [task-path] [--from=PHASE]` (resume)
+
+**Brainstorming flags**:
+
+- `--brainstorm`: Force brainstorming phase (auto-resolves Phase 2 brainstorming decision to "enable")
+- `--no-brainstorm`: Skip brainstorming phase
+- Neither: Phase 2 presents recommendation and asks user
+
+**Design flags**:
+
+- `--design`: Force high-level design phase (auto-resolves Phase 2 design decision to "enable")
+- `--no-design`: Skip high-level design phase
+- Neither: Phase 2 presents recommendation and asks user
+
+Task directory: `.owflow/tasks/research/YYYY-MM-DD-task-name/`

package/dist/skills/research/references/brainstorming-techniques.md

@@ -0,0 +1,84 @@
+# Brainstorming Techniques
+
+These techniques guide Phase 3 (Solution Brainstorming) of the research workflow. They provide patterns for expanding the solution space, evaluating alternatives, and managing scope.
+
+---
+
+### Divergent Thinking Techniques
+
+**Purpose**: Expand the solution space before narrowing. Generate quantity of ideas before evaluating quality.
+
+**HMW (How Might We) Questions**:
+- Transform research findings into opportunity statements
+- Format: "How might we [desired outcome] while [respecting constraint]?"
+- Generate 3-7 HMW questions from synthesis findings
+- Good HMW questions are neither too broad ("How might we solve everything?") nor too narrow ("How might we add a button?")
+- Each HMW should open multiple solution paths
+
+**SCAMPER Framework** (for alternative generation):
+- **S**ubstitute: What if we replaced component X with Y?
+- **C**ombine: What if we merged two approaches?
+- **A**dapt: What pattern from another domain applies here?
+- **M**odify: What if we changed the scale or emphasis?
+- **P**ut to other use: Can existing code serve a new purpose?
+- **E**liminate: What if we removed this constraint?
+- **R**everse: What if we did the opposite of the obvious approach?
+
+**Brainstorming Guardrails**:
+- Defer judgment during generation (evaluate later)
+- Build on existing ideas ("yes, and..." not "no, but...")
+- Aim for at least 3 genuine alternatives per decision area
+- Alternatives should be meaningfully different, not minor variations
+- Every alternative should be defensible by someone
+
+---
+
+### Convergent Thinking Techniques
+
+**Purpose**: Evaluate and select from generated alternatives using structured criteria.
+
+**5-Perspective Evaluation Matrix**:
+
+| Perspective | Assessment Focus | When It Dominates |
+|-------------|-----------------|-------------------|
+| Technical Feasibility | Implementation complexity, technology maturity | Tight timeline, limited expertise |
+| User Impact | UX improvement, adoption barriers, learning curve | User-facing features |
+| Simplicity | Maintenance burden, cognitive load, conceptual clarity | Long-lived systems |
+| Risk | Technical risk, schedule risk, reversibility | Critical systems, tight deadlines |
+| Scalability | Growth handling, performance at scale, extensibility | High-growth scenarios |
+
+**Trade-Off Patterns**:
+- **Satisficing**: Choose the first option that meets all minimum thresholds (good for low-stakes decisions)
+- **Optimizing**: Find the best option across weighted criteria (good for high-stakes, irreversible decisions)
+- **Elimination**: Remove options that fail any critical criterion, then compare survivors
+
+**Confidence-Weighted Selection**:
+- Weight evidence quality when comparing alternatives
+- High-confidence findings override low-confidence opinions
+- Note assumptions that, if wrong, would change the recommendation
+
+---
+
+### Scope Guardrail Patterns
+
+**Purpose**: Keep brainstorming focused on HOW to solve the identified problem, not WHETHER to expand scope.
+
+**Three-Zone Classification**:
+- **In-scope**: Directly addresses the research question as defined
+- **Stretch**: Related and valuable, but could be deferred to a follow-up task
+- **Out-of-scope**: Interesting but separate concern; capture and move on
+
+**Detection Signals for Scope Creep**:
+- Alternatives that require solving a different problem first
+- Trade-off analysis revealing missing prerequisites
+- User preferences that imply a larger project than originally scoped
+- "While we're at it" additions during dialogue
+
+**Deferred Idea Capture**:
+- Record every out-of-scope idea with a brief rationale for why it's worth considering later
+- Don't dismiss ideas - acknowledge value while maintaining focus
+- Deferred ideas feed into future research or initiative planning
+
+---
+
+This reference provides patterns and frameworks for the brainstorming phase. Actual implementation adapts these concepts to specific research contexts.

package/dist/skills/research/references/design-techniques.md

@@ -0,0 +1,40 @@
+# Design Techniques
+
+These techniques guide Phase 3 (High-Level Design) of the research workflow. They provide patterns for capturing and documenting design decisions in a durable, traceable format.
+
+---
+
+### Decision Documentation Patterns
+
+**Purpose**: Capture design decisions in a durable, traceable format.
+
+**Why Document Decisions**:
+- Future developers ask "why was this done this way?"
+- Prevents re-litigating settled questions
+- Preserves context that would otherwise be lost
+- Enables informed changes when assumptions change
+
+**MADR Format Overview** (Markdown Any Decision Record):
+- Lightweight, readable, version-control friendly
+- Sections: Status, Context, Decision Drivers, Considered Options, Decision Outcome, Consequences
+- Each decision is self-contained and independently understandable
+
+**When to Create an ADR**:
+- Decision affects system structure or component boundaries
+- Multiple viable alternatives existed (trade-offs involved)
+- Decision is hard to reverse later
+- Decision might be questioned by future developers
+
+**Lightweight vs Heavyweight**:
+- Lightweight (1 ADR, 10-20 lines): Simple designs with 1-2 key decisions
+- Standard (2-5 ADRs, 20-40 lines each): Most designs
+- Heavyweight (5+ ADRs): Complex systems with many interacting decisions
+
+**Decision Linking**:
+- Reference solution-exploration.md for alternatives already analyzed
+- Link from high-level-design.md decision table to individual ADR entries
+- ADRs from research inform (but don't replace) project-level ADRs in development
+
+---
+
+This reference provides patterns and frameworks for the design phase. Actual implementation adapts these concepts to specific research contexts.