[WIP] Implement documentation scaling based on scenario complexity

[Copilot]

Documentation Scaling Implementation Plan

• Phase 1: Research and Analysis

  • Review existing workflow patterns (simple, medium, complex)
  • Identify complexity indicators (steps, tools, MCP servers, network, repo-memory)
  • Analyze existing documentation examples (auto-close-parent-issues.md, metrics-collector.md)

• Phase 2: Create Documentation Templates

  • Create .github/instructions/templates/documentation-tiers.md with tier definitions
  • Define Simple tier template (inline comments only)
  • Define Medium tier template (README + quickstart)
  • Define Complex tier template (full 5-7 file suite)

• Phase 3: Update Agent Instructions

  • Update .github/agents/developer.instructions.md with complexity detection logic
  • Add documentation scaling guidelines
  • Add tier selection criteria

• Phase 4: Testing and Validation

  • Test with simple scenario (e.g., single PR comment workflow)
  • Test with medium scenario (e.g., issue triage workflow)
  • Test with complex scenario (e.g., multi-phase pipeline with repo-memory)
  • Validate documentation templates are clear and actionable

• Phase 5: Final Review

  • Run validation checks (make fmt, make test-unit)
  • Review all changes for consistency
  • Ensure acceptance criteria are met

Original prompt

---

This section details on the original issue you should resolve

<issue_title>[plan] Implement documentation scaling based on scenario complexity</issue_title>
<issue_description>## Objective

Implement logic to scale documentation based on scenario complexity, preventing documentation redundancy for simple use cases while maintaining comprehensive docs for complex scenarios.

Context

Research observed excellent but potentially overwhelming documentation (7-file bundles for some scenarios). Simple workflows may benefit from inline documentation, while complex multi-phase pipelines need comprehensive guides.

Approach

1. Define complexity tiers:

   • Simple (1-2 steps): Inline workflow comments only
   • Medium (3-5 steps): Quick start + main README
   • Complex (6+ steps): Full documentation suite

2. Add complexity detection logic to agent instructions:

   • Count distinct workflow phases/jobs
   • Detect tool integrations (Playwright, MCP, network allowlisting)
   • Check for persistence patterns (repo-memory)
   • Identify multi-system integrations

3. Create documentation templates for each tier:

   • Simple: Inline comment template with key configuration
   • Medium: 2-file template (README + quickstart)
   • Complex: 5-7 file template (README, quickstart, troubleshooting, architecture, examples)

4. Update agent instructions to choose appropriate documentation level

Files to Modify

• Update: .github/instructions/developer.instructions.md (add complexity detection + scaling logic)
• Create: .github/instructions/templates/documentation-tiers.md (documentation templates)

Acceptance Criteria

• Complexity detection logic defines 3 clear tiers
• Simple scenario (e.g., single PR comment) generates inline docs only
• Medium scenario (e.g., coverage check) generates 2-file bundle
• Complex scenario (e.g., flaky test tracking) generates full suite
• Templates include clear guidelines on when to use each tier
• Tested with 3 sample scenarios (one per tier)

Expected Impact

Reduces documentation overhead for simple workflows while maintaining comprehensive guides for complex automation, improving developer experience.
Related to #10285

AI generated by Plan Command for discussion #10248

Comments on the Issue (you are @copilot in this section)

• Fixes [plan] Implement documentation scaling based on scenario complexity #10287

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.