docs(signals): make sort=personal the first route for agents prioritizing an inbox #130804

Problem

Agents answering “what should I look at in my inbox?” are still directed to reconstruct a personal ranking themselves, even though the report list now serves the stored personal ranking.

PR #129978 merged sort=personal. A live MCP read on project 2 on 2026-11-06 with view=for_you, sort=personal, limit=10 returned ranker=personal and a ranking_id. However:

• prioritizing-my-inbox still asks agents to load the activity summary, gather 60–150 candidates across pools, and compute a bespoke score.
• inbox-reports-list describes the personal sort parameter, but its top-level “my inbox” guidance still says sort=priority.
• Inbox exploration and related discovery descriptions need consistent routing.

Andy wants the existing personal ranking to be the first place agents check for the user's best inbox items.

Requested change

Update the canonical user-facing inbox-exploration and prioritizing-my-inbox skills (the latter was referred to as “personalizing my inbox” in the request), plus the relevant MCP tool descriptions, to prefer the stored personal sort for personal prioritization requests.

Start a normal personal shortlist with:

{"view":"for_you","sort":"personal","limit":10}

Respect an explicitly requested count or filter. Resolve actual canonical source paths in the checkout; update generated skill/tool artifacts through the repository's normal generation workflow rather than only editing the live team skill copy.

Behavior and semantics

• Read ranker to distinguish actual personal ranking from the built-in recommended fallback. Do not claim personalization just because sort=personal was requested.
• Preserve returned ordering by default. Explain the returned reasons/state when available; do not silently replace the stored ranking with the old client-side scoring formula.
• This list read does not gather candidates, enqueue a build, or call an LLM. No usable personal row means recommended ordering; scheduled coverage being 50% does not mean the endpoint is unavailable to everyone else.
• Keep ranking_id from page one and pass it on later pages so a rebuild does not reorder pagination.
• Do not pass ordering with the preset: explicit ordering overrides sort.
• Do not impose the old default creation-time window on a generic “best items” request: it can exclude older reports that still need attention.
• Keep inbox-reports-for-me documented for its distinct on-demand/focus/freshness behavior; do not remove or conflate it with the pure list read. Use it when the user explicitly needs those capabilities.
• Explicit custom reranking, themes, broader project exploration, missing personal rankings, and diagnostics may need additional tools. Describe those as purposeful follow-ups, rather than the default expensive reconstruction.
• Keep all current authorization and work-log/claim safeguards for acting on reports.

Surfaces

• Skill descriptions and bodies for inbox-exploration and prioritizing-my-inbox.
• inbox-reports-list top-level guidance and sort parameter documentation.
• inbox-reports-for-me description and other related discovery text where necessary to make the two routes clear.
• Generated MCP definitions and distributed skills, following the owning source of truth.

Acceptance / verification

• “What's in my inbox?”, “my top 10”, and “what should I look at today?” consistently route first to view=for_you, sort=personal.
• Actual personal response, recommended fallback, empty results, explicit filtering, and page-two ranking stability are explained correctly.
• No default instructions require rebuilding a manual activity-summary/model scoring pipeline before reading the stored personal order.
• Tool and skill guidance agree; generation/drift checks pass.
• Verify an actual list read and record ranker plus presence/absence of ranking_id; do not change rollout, refresh rankings, or mutate inbox reports to test documentation.

This issue is documentation/discovery alignment, not a request to change ranking behavior, wire the web clients, alter the running ranking experiment, or widen rollout. Related: #129928 / #129978; personal-ranking capacity work #130723 / #130770.