Give the buddy a map of the app: get_app_guide

[DavidLeuter]

Short summary

Persona half of the buddy's app guide: routes questions about the Sprintstart app to the backend's new get_app_guide tool.

• New _APP_GUIDE_CLAUSE in both personas (hire buddy and team mode), only when get_app_guide is mounted:
  • questions about the app itself (where a page or button is, how to do something here, what this page is for) go to get_app_guide, never to search_docs, which describes the project, not the app;
  • "this page" / "here" means the page the guide says the user is on;
  • describe only pages the guide names, link them as in-app Markdown links (or a how-to's own deep link to the right tab);
  • never send somebody to a page the guide doesn't list as theirs; say who to ask instead.
• Tests for routing, the constraint, absence without the tool, and team mode.

Checks

• I verified the code makes sense intuitively
• The PR changes affect only this issue, no unrelated/unwanted code changes to other modules/code segments
• Local checks run (ruff, ruff format --check, pyright src/, pytest: 1077 passed)
• New logic is unit tested
• The new functionality is tested manually

Additional notes

Part of a three-repo change; each PR works on its own, but the feature needs all three:

• Backend: Give the buddy a map of the app: get_app_guide sprintstart-backend#277
• Frontend: Give the buddy a map of the app: get_app_guide sprintstart-frontend#301
• AI: Give the buddy a map of the app: get_app_guide #215

Not yet tried end to end with a real model.

🤖 Generated with Claude Code

[BabuPlk]

Read the diff at ed259dc against dev (86a4d68, already merged in), together with the backend side (BuddyAppGuideTools / AppGuide on sprintstart-backend#277) and the routes on sprintstart-frontend#301. Ran it locally: ruff check, ruff format --check, pyright on buddy_persona.py and pytest tests/onboarding (334 passed) are all green.

The prompt matches what the tool actually returns. "this page / here" maps to the guide's They are looking at: … line, "say who to ask" maps to its Only somebody else can do these section, and the how-to deep links (/team-management?tab=roles, /admin?tab=projects, /hire-setup?tab=arrival) are the ones the frontend reads from ?tab=. Gating on "get_app_guide" in available in both personas, plus the test that the clause is absent without the tool, keeps the "never mention a tool that isn't mounted" rule. Nothing here blocks merging. Two things are worth a look before the end-to-end try:

1. _NO_BUTTON_CLAUSE may make the model shy about naming the app's buttons

For a hire with action tools mounted, the persona says "Never describe a button instead of making one" and "Never tell them to confirm, click or check anything". That rule is about the chat's proposal buttons, but it doesn't say so. Then _APP_GUIDE_CLAUSE asks the model to describe "the pages and buttons the guide names", e.g. "Roles tab → New role". A model reading both could hedge on the second, or say something like "I can't add that button for you". A half-sentence in _APP_GUIDE_CLAUSE would clear it up, something like: "Buttons on the app's own pages aren't the chat buttons your tools make — naming those the guide names is fine." Worth checking in the end-to-end run in any case, with a hire who has complete_step etc. mounted.

2. Small things

• The example links are real paths. [Team](/team-management) is a page a team member can't open, and it's in every hire persona now. The "never send somebody to a page the guide does not list" line covers it, and the risk is low. Still, a placeholder like [Name](/path) or a page everyone has would remove the temptation. The test asserting the literal [Team](/team-management) would need to change along with it.
• Placement isn't tested. The comment says the clause sits right after the search_docs routing rule because it narrows it, but no test enforces that order. Something like persona.index("hire-state tools") < persona.index("get_app_guide") would keep a later edit from moving it away. Optional.
• "Call it before answering, even when you think you know" means one tool round-trip per app question, every time. That's the right trade-off, since the current page changes between turns. Just mentioning it so it isn't a surprise in latency.

---

What's good here

• The routing is aimed at the real failure. The tool spec and the persona both say why search_docs is wrong for app questions (the corpus is the project, not the app), so the model gets the reason and not just the rule.
• The persona only talks about access, the tool decides it. "Only pages the guide lists as theirs" puts the filtering in one place, in the backend.
• Both personas, one clause. Managers ask "where is …" at least as often as hires, and nothing in the wording assumes who is reading.
• Tests are small and each one pins one promise (routing, constraint, absence, team mode).

Approving from my side. 1 is a one-liner if you agree, and the rest is optional.

[DavidLeuter]

Thanks! Took all three in 8f64d51: the clause now says app buttons aren't the chat's proposal buttons (with a test), the example link is [Board](/board), and a test pins the clause after the search_docs routing rule. Agreed on the extra round-trip per app question — that's intended, since the current page changes between turns. I'll check the button wording in the end-to-end run with a hire who has action tools mounted.

[BabuPlk]

Re-reviewed 8f64d51. All three points are in:

• The clause now says app buttons aren't the chat's proposal buttons, and a test checks that both rules end up in the same persona.
• [Board](/board) is a safe example: in AppGuide it has the default roles = EVERYONE, so no reader gets a dead-end link from it.
• The new ordering test pins the clause after the search_docs routing rule.

Ran it locally again: ruff check, ruff format --check and pytest tests/onboarding (336 passed) are green, and CI is green too. Approving. Thanks for checking the button wording in the end-to-end run.