ADR-157: Research-to-Artifacts Plugin Pattern

Status

Accepted - 2026-02-04

Context

A common workflow in enterprise knowledge work involves:

Research - Searching web, documents, codebases for information on a topic
Analysis - Organizing, categorizing, and synthesizing findings
Artifact Generation - Producing multiple structured outputs (docs, diagrams, summaries)

This pattern appears in:

Product Discovery → Executive Summary + PRD + Competitive Analysis
Architecture Planning → SDD + TDD + ADRs + Diagrams
Market Research → Analysis Report + Strategy Brief + Glossary
Technology Evaluation → Comparison Matrix + Quick Start Guide + ADRs

Currently, each workflow requires custom orchestration. We need a reusable plugin pattern that:

Composes existing skills (search, analysis, document generation)
Fills gaps with new specialized skills
Produces consistent, downloadable artifact bundles

Decision

1. Research-to-Artifacts Pattern Architecture

┌──────────────────────────────────────────────────────────────────────────┐
│                   RESEARCH-TO-ARTIFACTS PLUGIN PATTERN                    │
├──────────────────────────────────────────────────────────────────────────┤
│                                                                           │
│  ┌─────────────┐                                                          │
│  │   INPUT     │  Topic + Date Range + Artifact Types + Output Format    │
│  └──────┬──────┘                                                          │
│         │                                                                 │
│         ▼                                                                 │
│  ┌──────────────────────────────────────────────────────────────────┐    │
│  │                    PHASE 1: RESEARCH                              │    │
│  │  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐               │    │
│  │  │ Web Search  │  │ Doc Search  │  │ Code Search │               │    │
│  │  │   Skill     │  │   Skill     │  │   Skill     │               │    │
│  │  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘               │    │
│  │         └────────────────┼────────────────┘                       │    │
│  │                          ▼                                        │    │
│  │                   Raw Research Data                               │    │
│  └──────────────────────────┬───────────────────────────────────────┘    │
│                             │                                             │
│                             ▼                                             │
│  ┌──────────────────────────────────────────────────────────────────┐    │
│  │                    PHASE 2: ANALYSIS                              │    │
│  │  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐               │    │
│  │  │  Organize   │  │ Categorize  │  │  Extract    │               │    │
│  │  │  & Cluster  │  │  & Tag      │  │  Insights   │               │    │
│  │  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘               │    │
│  │         └────────────────┼────────────────┘                       │    │
│  │                          ▼                                        │    │
│  │             Structured Knowledge Graph                            │    │
│  └──────────────────────────┬───────────────────────────────────────┘    │
│                             │                                             │
│                             ▼                                             │
│  ┌──────────────────────────────────────────────────────────────────┐    │
│  │                    PHASE 3: GENERATION                            │    │
│  │                                                                    │    │
│  │  ┌────────────┐ ┌────────────┐ ┌────────────┐ ┌────────────┐     │    │
│  │  │ Quick Start│ │ Executive  │ │    SDD     │ │   ADRs     │     │    │
│  │  │  Generator │ │  Summary   │ │ Generator  │ │ Generator  │     │    │
│  │  └─────┬──────┘ └─────┬──────┘ └─────┬──────┘ └─────┬──────┘     │    │
│  │        │              │              │              │             │    │
│  │  ┌─────┴──────┐ ┌─────┴──────┐ ┌─────┴──────┐ ┌─────┴──────┐     │    │
│  │  │  Glossary  │ │  Mermaid   │ │    TDD     │ │  Impact    │     │    │
│  │  │ Generator  │ │  Diagrams  │ │ Generator  │ │  Analysis  │     │    │
│  │  └─────┬──────┘ └─────┬──────┘ └─────┬──────┘ └─────┬──────┘     │    │
│  │        └──────────────┼──────────────┼──────────────┘             │    │
│  │                       ▼                                           │    │
│  └──────────────────────────────────────────────────────────────────┘    │
│                             │                                             │
│                             ▼                                             │
│  ┌─────────────┐                                                          │
│  │   OUTPUT    │  Artifact Bundle (ZIP) with all generated documents     │
│  └─────────────┘                                                          │
│                                                                           │
└──────────────────────────────────────────────────────────────────────────┘

2. Skill Composition Strategy

Existing Skills (Reuse):

Skill	Phase	Purpose
`llm-research-patterns`	Research	Web search, source validation
`competitive-analysis`	Research	Market/competitor research
`strategy-brief-generation`	Generation	Strategy documents
`adr-decision-workflow`	Generation	ADR creation
`documenting-architecture`	Generation	Architecture documentation
`mermaid-diagram-fixing`	Generation	Diagram validation

New Skills (Create):

Skill	Phase	Purpose
`executive-summary-generator`	Generation	1-page executive summaries
`sdd-generator`	Generation	Software Design Documents
`tdd-generator`	Generation	Technical Design Documents
`glossary-generator`	Analysis	Terminology extraction
`quick-start-guide-generator`	Generation	1-2-3 quick start guides
`mermaid-architecture-generator`	Generation	System architecture diagrams
`artifact-bundler`	Output	ZIP bundle creation

3. Plugin Manifest Schema

{
  "name": "research-to-artifacts",
  "version": "1.0.0",
  "type": "orchestrator",
  "description": "Transform research into downloadable artifact bundles",

  "inputs": {
    "topic": {
      "type": "string",
      "required": true,
      "description": "Research topic or question"
    },
    "date_range": {
      "type": "string",
      "default": "2025-2026",
      "description": "Year range for web search filtering"
    },
    "artifacts": {
      "type": "array",
      "items": {
        "enum": [
          "quick-start",
          "executive-summary",
          "sdd",
          "tdd",
          "adrs",
          "glossary",
          "architecture-diagrams",
          "workflow-diagrams",
          "impact-analysis"
        ]
      },
      "default": ["executive-summary", "quick-start", "glossary"]
    },
    "output_format": {
      "type": "string",
      "enum": ["markdown", "pdf", "html", "bundle"],
      "default": "bundle"
    }
  },

  "phases": [
    {
      "id": "research",
      "skills": ["llm-research-patterns", "competitive-analysis"],
      "parallel": true
    },
    {
      "id": "analysis",
      "skills": ["glossary-generator"],
      "depends_on": ["research"]
    },
    {
      "id": "generation",
      "skills_dynamic": true,
      "depends_on": ["analysis"],
      "skill_mapping": {
        "quick-start": "quick-start-guide-generator",
        "executive-summary": "executive-summary-generator",
        "sdd": "sdd-generator",
        "tdd": "tdd-generator",
        "adrs": "adr-decision-workflow",
        "glossary": "glossary-generator",
        "architecture-diagrams": "mermaid-architecture-generator",
        "workflow-diagrams": "mermaid-architecture-generator",
        "impact-analysis": "strategy-brief-generation"
      }
    },
    {
      "id": "bundle",
      "skills": ["artifact-bundler"],
      "depends_on": ["generation"]
    }
  ],

  "outputs": {
    "bundle_path": "string",
    "artifact_manifest": "object",
    "generation_report": "object"
  }
}

4. Artifact Templates

Each generated artifact follows a standard template:

Quick Start Guide Template

# {Topic} - Quick Start Guide

## Overview
{1-paragraph summary}

## Prerequisites
{Bulleted list of requirements}

## Step 1: {First Action}
{Detailed instructions}

## Step 2: {Second Action}
{Detailed instructions}

## Step 3: {Third Action}
{Detailed instructions}

## Next Steps
{Links to detailed documentation}

## Troubleshooting
{Common issues and solutions}

Executive Summary Template

# Executive Summary: {Topic}

**Date:** {Generated Date}
**Prepared For:** {Audience}

## Key Findings
{3-5 bullet points}

## Strategic Implications
{2-3 paragraphs}

## Recommendations
{Prioritized action items}

## Risk Assessment
{Identified risks with mitigation}

## Timeline & Resources
{High-level estimates}

Glossary Template

# Glossary: {Topic}

## Core Concepts

| Term | Definition | Context |
|------|------------|---------|
| {Term 1} | {Definition} | {Where used} |
| {Term 2} | {Definition} | {Where used} |

## Acronyms

| Acronym | Expansion | Usage |
|---------|-----------|-------|
| {ACR} | {Full form} | {Context} |

## Related Terms
{Cross-references to related concepts}

5. Plugin Directory Structure

plugins/enterprise/research-to-artifacts/
├── plugin.json                     # Plugin manifest
├── README.md                       # User documentation
├── CONNECTORS.md                   # MCP server config
├── .claude-plugin/
│   └── plugin.json                 # Claude Code compatibility
│
├── skills/
│   ├── executive-summary-generator/
│   │   └── SKILL.md
│   ├── sdd-generator/
│   │   └── SKILL.md
│   ├── tdd-generator/
│   │   └── SKILL.md
│   ├── glossary-generator/
│   │   └── SKILL.md
│   ├── quick-start-guide-generator/
│   │   └── SKILL.md
│   ├── mermaid-architecture-generator/
│   │   └── SKILL.md
│   └── artifact-bundler/
│       └── SKILL.md
│
├── commands/
│   ├── research.md                 # /r2a:research <topic>
│   ├── generate.md                 # /r2a:generate <artifacts>
│   └── bundle.md                   # /r2a:bundle
│
├── templates/
│   ├── quick-start.md
│   ├── executive-summary.md
│   ├── sdd.md
│   ├── tdd.md
│   ├── glossary.md
│   └── impact-analysis.md
│
├── config/
│   ├── defaults.json
│   └── artifact-schema.json
│
└── tests/
    └── integration-tests.yaml

6. Invocation Examples

# Full research-to-artifacts workflow
/r2a "AI agents in enterprise 2025-2026" --artifacts all

# Specific artifacts only
/r2a "Kubernetes best practices" --artifacts quick-start,glossary,diagrams

# Custom date range
/r2a "LLM fine-tuning techniques" --date-range 2024-2026 --artifacts sdd,tdd

# Research only (no generation)
/r2a:research "RAG architectures" --output research-notes.md

# Generate from existing research
/r2a:generate research-notes.md --artifacts executive-summary,adrs

# Bundle existing artifacts
/r2a:bundle ./my-artifacts/ --format zip

7. Dependency Graph

Consequences

Benefits

Reusability - One pattern for many research-to-documentation workflows
Composability - Mix and match existing + new skills
Consistency - All artifacts follow templates with consistent structure
Downloadable - Users get complete artifact bundles for offline use
Extensible - New artifact types can be added as skills

Trade-offs

Complexity - Multi-phase orchestration requires careful dependency management
Token Usage - Full workflow may consume significant context
Quality Control - Generated artifacts need MoE validation

Mitigation

Token Management: Use /cx checkpoints between phases
Quality Gates: Apply /moe-judges to generated artifacts
Incremental Mode: Allow phase-by-phase execution with persistence

Implementation Plan

Phase	Deliverable	Track
1	Create 7 new skills	H.8
2	Create plugin scaffold	H.8
3	Implement orchestrator	H.8
4	Add templates	F
5	Integration tests	E
6	Documentation	F

ADR-152: Enterprise Plugin Architecture
ADR-153: Plugin Development Framework
ADR-156: Project-Scoped Context Databases

8. Quality Gates

MoE verification checkpoints between phases ensure quality before proceeding:

"quality_gates": {
  "post_research": {
    "skill": "moe-judges",
    "criteria": ["source_diversity", "recency", "relevance"],
    "min_confidence": 0.85,
    "action_on_fail": "retry_with_expanded_search"
  },
  "post_analysis": {
    "skill": "council-review",
    "criteria": ["completeness", "accuracy", "organization"],
    "min_confidence": 0.90,
    "action_on_fail": "human_review"
  },
  "post_generation": {
    "skill": "uncertainty-quantification",
    "criteria": ["factual_accuracy", "template_compliance", "cross_reference_validity"],
    "min_confidence": 0.88,
    "action_on_fail": "flag_for_review"
  }
}

Existing Skills for Quality Gates:

moe-judges - Multi-model evaluation panel
council-review - Multi-perspective review
uncertainty-quantification - Confidence scoring

9. Source Attribution & Provenance

Track where each fact originated for transparency and verification:

## Key Finding
"AI agent market projected to reach $X billion by 2027"
[Source: Gartner Report 2025-12, confidence: 0.92, retrieved: 2026-02-04]

Schema:

{
  "claim": "string",
  "source": {
    "title": "string",
    "url": "string",
    "date_published": "date",
    "date_retrieved": "date",
    "author": "string"
  },
  "confidence": 0.92,
  "cited_in_artifacts": ["executive-summary.md", "glossary.md"]
}

New Skill: source-attribution-tracker

Links claims to sources
Tracks citation chains
Generates bibliography
Validates source freshness

10. Incremental Mode

Support updating artifacts without full re-research:

"incremental_mode": {
  "enabled": true,
  "cache_ttl_days": 7,
  "update_strategy": "delta_only",
  "preserve_manual_edits": true,
  "checksum_tracking": true
}

Invocation:

# Update existing research (only fetch new sources)
/r2a "AI agents" --incremental --since 2026-01-01

# Regenerate specific artifacts from cached research
/r2a:generate --from-cache --artifacts executive-summary

# Force full refresh
/r2a "AI agents" --force-refresh

Existing Skill: checkpoint-automation - State persistence between runs

11. Human-in-the-Loop Checkpoints

Optional review points before expensive generation:

# Pause after research for human review
/r2a "topic" --review-after research

# Pause after analysis
/r2a "topic" --review-after analysis

# Pause before bundling
/r2a "topic" --review-after generation

# Multiple checkpoints
/r2a "topic" --review-after research,analysis

# Full auto (no pauses - default)
/r2a "topic" --auto

Review Interface:

┌─────────────────────────────────────────────────┐
│  CHECKPOINT: Post-Research Review               │
├─────────────────────────────────────────────────┤
│  Sources Found: 47                              │
│  Unique Domains: 12                             │
│  Date Range: 2025-01 to 2026-02                 │
│  Confidence: 0.87                               │
│                                                 │
│  [View Sources] [Edit Query] [Continue] [Abort]│
└─────────────────────────────────────────────────┘

12. Multi-Model Orchestration

Route different phases to optimal models:

Phase	Model	Rationale
Research	Sonnet	Fast, good at search synthesis
Analysis	Opus	Deep reasoning, pattern detection
Quick Start	Haiku	Concise, efficient for simple docs
SDD/TDD	Opus	Technical depth required
Diagrams	Sonnet	Good at Mermaid syntax
Glossary	Haiku	Term extraction is straightforward

Configuration:

"model_routing": {
  "research": "claude-sonnet-4",
  "analysis": "claude-opus-4-5",
  "generation": {
    "quick-start": "claude-haiku-4-5",
    "executive-summary": "claude-opus-4-5",
    "sdd": "claude-opus-4-5",
    "tdd": "claude-opus-4-5",
    "glossary": "claude-haiku-4-5",
    "diagrams": "claude-sonnet-4"
  }
}

Existing Skill: multi-provider-llm-fallback

13. Artifact Cross-Referencing

Automatically link related artifacts:

<!-- In Executive Summary -->
See [Glossary](./glossary.md#term-name) for definition.
See [Architecture Diagram](./diagrams/system-architecture.md) for visual.
Detailed in [SDD Section 3.2](./sdd.md#32-component-design).

New Skill: artifact-cross-linker

Generates inter-document links
Creates unified table of contents
Validates all cross-references
Builds artifact dependency graph

14. Template Customization

Support organization-specific templates:

plugins/research-to-artifacts/
├── templates/
│   ├── default/              # Built-in templates
│   │   ├── executive-summary.md
│   │   └── quick-start.md
│   └── custom/               # User overrides
│       ├── enterprise/       # Enterprise template set
│       ├── startup/          # Startup template set
│       └── academic/         # Academic template set

Invocation:

/r2a "topic" --template-set enterprise
/r2a "topic" --template-set startup
/r2a "topic" --template ./my-templates/

15. Confidence Scoring per Artifact

Each artifact receives a quality assessment:

{
  "artifact_manifest": {
    "executive-summary.md": {
      "confidence": 0.94,
      "sources_cited": 12,
      "moe_score": 0.91,
      "warnings": [],
      "generated_at": "2026-02-04T15:30:00Z"
    },
    "quick-start.md": {
      "confidence": 0.88,
      "sources_cited": 5,
      "moe_score": 0.85,
      "warnings": ["limited_examples_found"],
      "generated_at": "2026-02-04T15:32:00Z"
    },
    "sdd.md": {
      "confidence": 0.72,
      "sources_cited": 8,
      "moe_score": 0.78,
      "warnings": ["technical_depth_insufficient", "needs_review"],
      "generated_at": "2026-02-04T15:35:00Z"
    }
  }
}

Existing Skill: uncertainty-quantification

16. Export Format Options

Beyond ZIP bundle:

/r2a "topic" --output-format zip         # Default - all files in ZIP
/r2a "topic" --output-format pdf         # Single PDF with all artifacts
/r2a "topic" --output-format notion      # Notion import format
/r2a "topic" --output-format confluence  # Confluence wiki markup
/r2a "topic" --output-format obsidian    # Obsidian vault with links
/r2a "topic" --output-format docx        # Word document per artifact

New Skill: artifact-format-converter

17. Novelty Detection

Highlight unique or surprising findings:

## Key Findings

### Expected (Aligned with Prior Research)
- AI adoption increasing in enterprise (aligned with 2024 trends)
- Cost reduction primary driver (consistent with industry reports)

### Novel Insights ⭐
- **Unexpected:** 43% of enterprises report AI "shadow IT" (unreported usage)
- **Emerging:** "AI agents" terminology replacing "copilots" in Q4 2025
- **Contrarian:** Open-source models outperforming proprietary in 3 categories

### Contradictions ⚠️
- Source A claims X, but Source B claims Y (flagged for review)

Existing Skill: novelty-detection-patterns

18. Competitive Comparison Mode

When researching products/technologies:

/r2a "Kubernetes alternatives 2025-2026" --mode competitive

Additional Artifacts Generated:

comparison-matrix.md - Feature comparison table
migration-paths.md - How to switch between options
decision-framework.md - Criteria for choosing
vendor-analysis.md - Company stability, support, pricing

Existing Skill: competitive-analysis

19. Enhanced Dependency Graph

Consequences

Benefits

Reusability - One pattern for many research-to-documentation workflows
Composability - Mix and match existing + new skills
Consistency - All artifacts follow templates with consistent structure
Downloadable - Users get complete artifact bundles for offline use
Extensible - New artifact types can be added as skills
Quality Assured - MoE gates prevent low-quality output
Traceable - Source attribution enables fact-checking
Incremental - Updates don't require full re-research
Multi-Format - Export to various platforms

Trade-offs

Complexity - Multi-phase orchestration requires careful dependency management
Token Usage - Full workflow may consume significant context
Quality Control - Generated artifacts need MoE validation
Latency - Quality gates add processing time

Mitigation

Token Management: Use /cx checkpoints between phases
Quality Gates: Apply /moe-judges to generated artifacts
Incremental Mode: Allow phase-by-phase execution with persistence
Caching: Cache research results for 7 days by default
Model Routing: Use efficient models for simple tasks

Implementation Plan

Phase	Deliverable	Track	Priority
1	Create 7 core skills	H.8	P0
2	Create plugin scaffold	H.8	P0
3	Implement orchestrator	H.8	P0
4	Add quality gates	H.8	P1
5	Add source attribution	H.8	P1
6	Add incremental mode	H.8	P2
7	Add multi-model routing	H.8	P2
8	Add format converters	H.8	P3
9	Add templates	F	P1
10	Integration tests	E	P1
11	Documentation	F	P1

New Skills Summary

Skill	Phase	Priority	Purpose
`executive-summary-generator`	Generation	P0	1-page executive summaries
`sdd-generator`	Generation	P0	Software Design Documents
`tdd-generator`	Generation	P0	Technical Design Documents
`glossary-generator`	Analysis	P0	Terminology extraction
`quick-start-guide-generator`	Generation	P0	1-2-3 quick start guides
`mermaid-architecture-generator`	Generation	P0	System architecture diagrams
`artifact-bundler`	Output	P0	ZIP/PDF/multi-format bundle
`source-attribution-tracker`	Analysis	P1	Provenance tracking
`artifact-cross-linker`	Output	P1	Inter-document linking
`artifact-format-converter`	Output	P3	Format conversion

ADR-152: Enterprise Plugin Architecture
ADR-153: Plugin Development Framework
ADR-156: Project-Scoped Context Databases
ADR-060: MoE Verification Layer (quality gates)
ADR-136: CODITECT Experience Framework (skill loading)

Version: 1.1.0 Created: 2026-02-04 Updated: 2026-02-04 Author: Claude (Opus 4.5) Track: H (Framework Autonomy)

Status​

Context​

Decision​

1. Research-to-Artifacts Pattern Architecture​

2. Skill Composition Strategy​

3. Plugin Manifest Schema​

4. Artifact Templates​

Quick Start Guide Template​

Executive Summary Template​

Glossary Template​

5. Plugin Directory Structure​

6. Invocation Examples​

7. Dependency Graph​

Consequences​

Benefits​

Trade-offs​

Mitigation​

Implementation Plan​

Related ADRs​

8. Quality Gates​

9. Source Attribution & Provenance​

10. Incremental Mode​

11. Human-in-the-Loop Checkpoints​

12. Multi-Model Orchestration​

13. Artifact Cross-Referencing​

14. Template Customization​

15. Confidence Scoring per Artifact​

16. Export Format Options​

17. Novelty Detection​

18. Competitive Comparison Mode​

19. Enhanced Dependency Graph​

Consequences​

Benefits​

Trade-offs​

Mitigation​

Implementation Plan​

New Skills Summary​

Related ADRs​

Status

Context

Decision

1. Research-to-Artifacts Pattern Architecture

2. Skill Composition Strategy

3. Plugin Manifest Schema

4. Artifact Templates

Quick Start Guide Template

Executive Summary Template

Glossary Template

5. Plugin Directory Structure

6. Invocation Examples

7. Dependency Graph

Consequences

Benefits

Trade-offs

Mitigation

Implementation Plan

Related ADRs

8. Quality Gates

9. Source Attribution & Provenance

10. Incremental Mode

11. Human-in-the-Loop Checkpoints

12. Multi-Model Orchestration

13. Artifact Cross-Referencing

14. Template Customization

15. Confidence Scoring per Artifact

16. Export Format Options

17. Novelty Detection

18. Competitive Comparison Mode

19. Enhanced Dependency Graph

Consequences

Benefits

Trade-offs

Mitigation

Implementation Plan

New Skills Summary

Related ADRs