[Code Quality] Document standardized 4-job workflow pattern as best practice

[github-actions]

Description

All 144 agentic workflows in the repository follow a consistent 4-job pattern (activation → agent → detection → conclusion), but this architectural pattern is not documented. Creating documentation for this pattern would help developers understand workflow structure and maintain consistency when creating new workflows.

Identified by

Agentic Workflow Lock File Statistics #12763

Current Pattern

100% of workflows use this structure:

1. activation job - Pre-flight checks and timestamp validation
2. agent job - Main agent execution
3. detection job - Trigger detection logic (conditional)
4. conclusion job - Post-processing and cleanup

Additional conditional jobs:

• schedule job (103 workflows) - Schedule-specific activation
• issues job (13 workflows) - Issue-specific activation
• discussion job (4 workflows) - Discussion-specific activation

Key Characteristics

Job Dependencies:

• Activation → Agent (agent needs activation to complete)
• Agent → Conclusion (conclusion waits for agent)
• Detection runs parallel to agent

Runner Distribution:

• ubuntu-slim for activation jobs (fast startup)
• ubuntu-latest for agent jobs (full capabilities)

Timeout Patterns:

• Activation: 5-10 minutes (quick checks)
• Agent: 15-20 minutes (main work)
• Conclusion: 10 minutes (cleanup)

Documentation to Create

Proposed Location: docs/src/content/docs/guides/workflow-architecture.md

Content to Include:

1. Overview - Why all workflows follow this pattern
2. Job Descriptions - Purpose and responsibility of each job
3. Job Dependencies - How jobs depend on each other
4. Runner Selection - When to use ubuntu-slim vs ubuntu-latest
5. Timeout Guidelines - Recommended timeouts for each job type
6. Permission Patterns - How permissions are scoped per job
7. Conditional Jobs - When to add trigger-specific activation jobs
8. Examples - Show minimal and full workflow structures

Success Criteria

• New documentation page created explaining the 4-job pattern
• Includes diagrams showing job flow and dependencies
• Examples demonstrate minimal and complex patterns
• Linked from main documentation navigation
• Helps developers understand existing workflows and create new ones consistently

Benefits

• Onboarding: New developers understand workflow structure quickly
• Consistency: Maintains architectural consistency across workflows
• Best Practices: Documents proven patterns from 144 production workflows
• Troubleshooting: Helps debug workflow issues by understanding intended flow

Estimated Effort

2 hours (documentation writing and diagram creation)

Priority

Medium - Documentation improvement that aids developer understanding

References

• Lockfile Statistics Discussion #12763
• See discussion for complete statistical analysis of workflow patterns

AI generated by Discussion Task Miner - Code Quality Improvement Agent

• expires on Feb 13, 2026, 5:15 PM UTC