[plan] Implement documentation scaling based on scenario complexity

[github-actions]

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

[github-actions]

🍪 Issue Monster has assigned this to Copilot!

I've identified this issue as a good candidate for automated resolution and assigned it to the Copilot agent.

The Copilot agent will analyze the issue and create a pull request with the fix.

Om nom nom! 🍪

AI generated by Issue Monster