[information-architecture] Core workflow docs links point to missing pages, creating onboarding dead ends

[github-actions]

Information Architecture Findings

1. Core workflow entry links resolve to missing pages

Area: Navigation
Component(s): mkdocs.yml, docs/index.md, docs/workflows/gh-agent-workflows.md, docs/workflows/gh-agent-workflows/

Problem:
The primary onboarding paths (homepage + sidebar + workflow overview) direct users to core workflow docs that do not exist in docs/workflows/gh-agent-workflows/. Users hit dead ends exactly where first-time navigation should be clearest.

Evidence:

• mkdocs.yml:31-34 links Core Workflows to:
  • workflows/gh-agent-workflows/issue-triage.md
  • workflows/gh-agent-workflows/mention-in-issue.md
  • workflows/gh-agent-workflows/mention-in-pr.md
  • workflows/gh-agent-workflows/pr-review.md
• docs/index.md:54-58 links the same pages (plus pr-actions-detective.md) as “These five workflows ship with the install command above”.
• docs/workflows/gh-agent-workflows.md:59,63 links issue-triage.md and pr-review.md in Event-driven workflows.
• Present files under docs/workflows/gh-agent-workflows/ are only:
  • bugs.md, code-complexity.md, code-duplication.md, create-comment-on-issue.md, docs-patrol-overview.md, newbie-contributor.md, stale-issues.md, test-coverage.md, text-quality.md
    (none of the linked core pages exist there).

Suggested improvement:
Align IA across entry points by either:

• adding the missing core workflow docs at the linked paths, or
• retargeting all core-workflow links in nav/homepage/overview to existing canonical pages.

Also add CI link-checking for MkDocs nav and in-doc relative links to prevent future dead-end routes.

Suggested Actions

• Decide canonical locations for Issue Triage, Mention in Issue, Mention in PR, PR Review, and PR Actions Detective docs.
• Update mkdocs.yml, docs/index.md, and docs/workflows/gh-agent-workflows.md so all core links resolve consistently.
• Add/enable docs link validation in CI to fail on missing relative targets.

---

What is this? | From workflow: Trigger Information Architecture

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

[github-actions]

This issue was labeled stale on 2026-06-26 and has had no further activity for 30 days. Closing automatically. If this issue is still relevant, please reopen it.