1529 Research Patterns 40279c03

Shared Research Patterns for All Agents

Purpose: Eliminate duplication across agents by providing common research patterns, validation workflows, and confidence gates used throughout the 7-step workflow.

Standard Research Workflow

All agents follow this common pattern (adapt steps 3-4 for domain-specific needs):

┌──────────────────────────────────────────────────────────────┐
│ Step 1: Validate Prerequisites                               │
│   → Check previous agent's artifact exists                   │
│   → If missing, STOP and request handoff                     │
├──────────────────────────────────────────────────────────────┤
│ Step 2: Read Agent Context                                   │
│   → Read template structure (skip content reprocessing)      │
│   → Reference shared defaults (cached)                       │
│   → Read previous artifact for context (not re-query Azure)  │
├──────────────────────────────────────────────────────────────┤
│ Step 3: Domain-Specific Research                             │
│   → Perform agent-specific queries/analysis                  │
│   → Query external sources ONLY for new information          │
├──────────────────────────────────────────────────────────────┤
│ Step 4: Confidence Gate (80% Rule)                           │
│   → Verify sufficient context to proceed                     │
│   → If < 80%, ASK user for clarification                     │
└──────────────────────────────────────────────────────────────┘

Validation Checklist Pattern

Prerequisites Validation

Every agent should validate its inputs using this pattern:

**BEFORE {agent task}, verify:**

- [ ] Previous artifact exists: `agent-output/{project}/{artifact-number}-*.md`
- [ ] Artifact is complete (has all required H2 sections from template)
- [ ] No blockers or warnings in previous step

**If validation fails**: STOP and request handoff to previous agent.

Template Structure Reference

DO NOT re-read template contents during workflow execution.

Templates define output structure - reference them for H2 headers only:

Optimization: Read template ONCE at agent initialization, cache H2 structure.

Context Reading Pattern

DO: Read previous agent's artifact for context
DON'T: Re-query external APIs for information already in artifacts

## Context Reuse (Efficient)

1. **Requirements → Architect**:
   - Architect reads `01-requirements.md` for project scope, NFRs, compliance
   - SKIP re-querying user or workspace for same information

2. **Architect → Bicep Plan**:
   - Bicep Plan reads `02-architecture-assessment.md` for resource list, SKU decisions
   - SKIP re-querying Azure docs for resources already assessed

3. **Bicep Plan → Bicep Code**:
   - Bicep Code reads `04-implementation-plan.md` for AVM modules, dependencies
   - SKIP re-scanning workspace for AVM availability (already documented)

4. **Bicep Code → Deploy**:
   - Deploy reads `05-implementation-reference.md` for template paths
   - SKIP re-validating Bicep syntax if implementation ref confirms validation

## Shared Information Sources

Shared Defaults (Cached)

All agents reference .github/agents/_shared/defaults.md for:

• Default regions (swedencentral, germanywestcentral)
• Required tags (Environment, ManagedBy, Project, Owner)
• Naming conventions (CAF patterns)
• Security baseline (TLS 1.2+, HTTPS-only, etc.)

Optimization: Read once per session, cache in agent context.

Confidence Gate Pattern (80% Rule)

Universal confidence threshold: Proceed when you have 80% confidence in having sufficient context.

Confidence Assessment Criteria

Domain-Specific Confidence Criteria

Requirements Agent

Confidence = Are all critical NFRs defined?

• SLA target, RTO, RPO documented
• Compliance requirements identified (or confirmed none)
• Budget constraints known
• Scale/performance targets specified

Architect Agent

Confidence = Can I assess all WAF pillars?

• All required Azure services identified
• SKU options researched
• Cost estimates calculable
• Security/compliance requirements clear

Bicep Plan Agent

Confidence = Can I plan all implementations?

• All resources have AVM modules (or justification for raw Bicep)
• Dependencies mapped
• Governance constraints discovered
• Naming/tagging strategy defined

Bicep Code Agent

Confidence = Can I generate valid Bicep?

• Implementation plan complete
• AVM schemas fetched (preflight check passed)
• Module structure determined
• No blocking governance policies

Deploy Agent

Confidence = Can I deploy safely?

• Bicep templates validated
• What-if analysis successful
• Azure credentials confirmed
• Resource group exists or can be created

Anti-Patterns to Avoid

❌ Don't: Re-Query Same Information

<!-- BAD: Architect queries Azure docs for services already in requirements -->
Requirements document lists: "Azure SQL Database, App Service, Key Vault"
Architect queries: "What is Azure SQL Database?" (redundant if already documented)

<!-- GOOD: Architect reads requirements, queries ONLY for architecture decisions -->
Requirements document lists: "Azure SQL Database"
Architect queries: "Azure SQL Database SKU comparison for 99.95% SLA" (new info)

❌ Don't: Search Workspace Repeatedly

<!-- BAD: Every agent searches agent-output/ -->
Requirements: search_workspace("agent-output/")
Architect: search_workspace("agent-output/")  ← redundant
Bicep Plan: search_workspace("agent-output/") ← redundant

<!-- GOOD: First agent searches, passes context via artifacts -->
Requirements: search_workspace("agent-output/"), create 01-requirements.md
Architect: read 01-requirements.md (context already gathered)

❌ Don't: Re-validate Previous Work

<!-- BAD: Bicep Code re-validates governance already discovered -->
Bicep Plan: Run ARG query for Azure Policies → 04-governance-constraints.md
Bicep Code: Run ARG query again for same policies ← redundant

<!-- GOOD: Bicep Code reads governance artifact -->
Bicep Plan: Run ARG query → 04-governance-constraints.md
Bicep Code: Read 04-governance-constraints.md (constraints already discovered)

✅ Do: Validate Fresh State (When Needed)

<!-- GOOD: Deploy runs what-if (state changes since planning) -->
Bicep Plan: Plan resources based on requirements
Bicep Code: Generate templates
Deploy: Run what-if ← REQUIRED (actual Azure state may have changed)

Optimization Summary

When to Re-Query/Re-Validate

Re-query external sources when:

• User explicitly requests refresh ("update cost estimate", "check latest AVM versions")
• Artifact is stale (timestamp > 30 days old - future enhancement)
• Previous validation failed or artifact missing
• Actual Azure state needs verification (Deploy agent what-if)

Don't re-query when:

• Information already in previous artifact
• No material change expected (regional defaults, templates)
• Agent is delegating work that includes the query

Implementation Guidance

For agent developers adding new agents:

1. Reference this file in agent definition frontmatter
2. Follow validation pattern for prerequisites
3. Read artifacts, not raw data for context
4. Use 80% confidence gate for consistency
5. Document domain-specific confidence criteria

Example agent integration:

## Research Requirements (MANDATORY)

> **See [Research Patterns](_shared/research-patterns.md)** for shared validation
> and confidence gate patterns used across all agents.

<research_mandate>
**MANDATORY: Before {agent task}, run research following shared patterns.**

### Step 1: Validate Prerequisites (Standard Pattern)
<!-- Reference shared pattern -->
- Confirm `{previous-artifact}.md` exists in `agent-output/{project}/`
- Read artifact for context
- If missing, STOP and request handoff

### Step 2: Read Agent Context (Standard Pattern)
<!-- Reference shared pattern -->
- Reference template for H2 structure only
- Read shared defaults (cached)
- Skip workspace search (context in artifacts)

### Step 3: Domain-Specific Research
<!-- Agent-specific queries -->
- {Agent-specific research tasks}
- Query ONLY for information not in previous artifacts

### Step 4: Confidence Gate (Standard 80% Rule)
<!-- Reference shared pattern -->
Only proceed when you have **80% confidence** in:
- {Domain-specific confidence criteria}

If below 80%, ASK user for clarification.
</research_mandate>