[information-architecture] Detector/fixer chaining quick-start hides required workflow permissions

Start with docs/workflows/detector-fixer-chaining.md:18-35 and compare its primary chaining snippet with the permissions blocks at lines 7-11 of the four example-chained.yml files. Add the required in-context permissions guidance and keep the late-page note as reinforcement. Done means the first copy/paste path clearly covers write scopes for issue and pull-request creation.

Information Architecture Findings

1. Chaining quick-start snippet omits required permissions in the primary setup path

Area: Action placement / Progressive disclosure
Component(s): docs/workflows/detector-fixer-chaining.md, gh-agent-workflows/bug-hunter/example-chained.yml, gh-agent-workflows/code-complexity-detector/example-chained.yml, gh-agent-workflows/code-duplication-detector/example-chained.yml, gh-agent-workflows/test-coverage-detector/example-chained.yml

Problem: The first "How it works" chaining snippet is positioned as the primary copy/paste setup path, but it does not include a permissions: block. The required permission guidance is deferred to a late-page note, so users can complete setup from the top of the page and miss a control that governs whether the fixer can actually write PR changes.

Evidence:

• docs/workflows/detector-fixer-chaining.md:18-35 shows the initial detector→fixer snippet without permissions:.
• docs/workflows/detector-fixer-chaining.md:179 introduces required permission guidance much later ("union of both workflows' permissions").
• Chained examples in workflow directories place permissions near the top:
  • gh-agent-workflows/bug-hunter/example-chained.yml:7-11
  • gh-agent-workflows/code-complexity-detector/example-chained.yml:7-11
  • gh-agent-workflows/code-duplication-detector/example-chained.yml:7-11
  • gh-agent-workflows/test-coverage-detector/example-chained.yml:7-11

Suggested improvement: Move permission requirements into the first chaining snippet (or immediately adjacent callout) so the required control is in-context at the moment users copy setup instructions.

Suggested Actions

• Add a permissions: block to the first chaining snippet in docs/workflows/detector-fixer-chaining.md.
• Add a brief in-context note before the snippet stating that chaining requires write scopes for both issue creation and PR creation.
• Keep the late-page note, but make it reinforcement instead of first disclosure.

What is this? | From workflow: Trigger Information Architecture

Give us feedback! React with 🚀 if perfect, 👍 if helpful, 👎 if not.