Title: Docs: Add decision framework for when to add human members · Issue #313 · github/squad · GitHub
Open Graph Title: Docs: Add decision framework for when to add human members · Issue #313 · github/squad
X Title: Docs: Add decision framework for when to add human members · Issue #313 · github/squad
Description: Problem The docs explain what human members are and how they work (pausing, routing, stale reminders), but they don't answer the key question new users ask: When should I add someone as a human member vs. just @mention them on PRs? This ...
Open Graph Description: Problem The docs explain what human members are and how they work (pausing, routing, stale reminders), but they don't answer the key question new users ask: When should I add someone as a human mem...
X Description: Problem The docs explain what human members are and how they work (pausing, routing, stale reminders), but they don't answer the key question new users ask: When should I add someone as a human...
Opengraph URL: https://github.com/github/squad/issues/313
X: @github
Domain: github.com
{"@context":"https://schema.org","@type":"DiscussionForumPosting","headline":"Docs: Add decision framework for when to add human members","articleBody":"## Problem\n\nThe docs explain **what** human members are and **how** they work (pausing, routing, stale reminders), but they don't answer the key question new users ask:\n\n> **When should I add someone as a human member vs. just @mention them on PRs?**\n\nThis came up during onboarding — the distinction between a casual contributor and a roster-listed human isn't documented anywhere.\n\n## What's missing\n\n### Decision framework (the litmus test)\n- **Add to roster** when the person is a **decision gate** — someone the team should actively route to, wait on, and track (e.g., `Brady needs to approve architecture decisions before we build`)\n- **Don't add** when the person is a **collaborator you interact with through normal GitHub flows** — commenting on PRs, reviewing code, filing issues\n\n### Specific gaps across docs\n| Question | Current coverage |\n|----------|-----------------|\n| When should I add a human vs. @mention them? | Not addressed |\n| Casual contributors vs. roster members? | Not addressed |\n| What if I have 20 people — do all go on roster? | Not addressed |\n| Solo project — should I roster myself? | Not addressed |\n\n### Where this guidance should live\n1. **`.squad/templates/human-members.md`** — the authoritative template (see companion issue for creating this file)\n2. **`docs/src/content/docs/features/human-team-members.md`** — user-facing docs page\n3. **`docs/src/content/docs/concepts/your-team.md`** — team composition overview\n\n## Proposed decision framework\n\nAdd a section like:\n\n### When to add a human member\n\n| Scenario | Add to roster? | Why |\n|----------|---------------|-----|\n| Approves architecture decisions before implementation | ✅ Yes | Decision gate — team should route and wait |\n| Reviews all docs PRs as a standing reviewer | ✅ Yes | Recurring review gate |\n| Occasionally reviews PRs when tagged | ❌ No | Use @mention on the PR |\n| Files issues and contributes code | ❌ No | Normal GitHub collaboration |\n| Makes final ship/no-ship call | ✅ Yes | Approval gate |\n\n**The litmus test:** If you want agents to *stop and wait* for someone's input before proceeding on a specific type of work, add them. If they review asynchronously via GitHub, don't bother.\n\n## Acceptance criteria\n\n- [ ] Decision framework added to `human-team-members.md` docs page\n- [ ] Brief mention added to `your-team.md` (link to full framework)\n- [ ] Template file includes the framework (if created — see companion issue)","author":{"url":"https://github.com/diberry","@type":"Person","name":"diberry"},"datePublished":"2026-03-09T15:38:53Z","url":"https://github.com/github/squad/issues/313"}
| react-profiling | 0 |
| react-import-map | react,react-dom,react-dom/client,react-dom/profiling,react-is,react/compiler-runtime,react/jsx-dev-runtime,react/jsx-runtime,scheduler@b8488ee2c322 |
| route-pattern | /_view_fragments/issues/show/:user_id/:repository/:id/issue_layout(.:format) |
| route-controller | voltron_issues_fragments |
| route-action | issue_layout |
| fetch-nonce | v2:8778a9bd-f33e-29ba-595f-d2a3af4cb253 |
| current-catalog-service-hash | 81bb79d38c15960b92d99bca9288a9108c7a47b18f2423d0f6438c5b7bcd2114 |
| request-id | 8884:38C5CF:1EB1E7D:26FCAC5:6B014B16 |
| html-safe-nonce | 7d6aade9667b4a18207aac8e706f28aeb574dbd0a1f29b81dfb53751f465e1d5 |
| visitor-payload | eyJyZWZlcnJlciI6IiIsInJlcXVlc3RfaWQiOiI4ODg0OjM4QzVDRjoxRUIxRTdEOjI2RkNBQzU6NkIwMTRCMTYiLCJ2aXNpdG9yX2lkIjoiNjM5NDYyMTc2OTA4MDE5NTg2MiIsInJlZ2lvbl9lZGdlIjoiaWFkIiwicmVnaW9uX3JlbmRlciI6ImlhZCJ9 |
| visitor-hmac | a4d21b96d37da1f6a330774ef20eeb2e2897f7c09957db46eb4a29a62fd0ddee |
| hovercard-subject-tag | issue:4046321923 |
| github-keyboard-shortcuts | repository,issues,copilot |
| google-site-verification | Apib7-x98H0j5cPqHWwSMm6dNU4GmODRoqxLiDzdx9I |
| octolytics-url | https://collector.github.com/github/collect |
| analytics-location | / |
| fb:app_id | 1401488693436528 |
| apple-itunes-app | app-id=1477376905, app-argument=https://github.com/_view_fragments/issues/show/github/squad/313/issue_layout |
| twitter:image | https://opengraph.githubassets.com/7dfefc007bae12bea214b3a1863098079343bfa57501ecc9940fa00133099bcf/github/squad/issues/313 |
| twitter:card | summary_large_image |
| og:image | https://opengraph.githubassets.com/7dfefc007bae12bea214b3a1863098079343bfa57501ecc9940fa00133099bcf/github/squad/issues/313 |
| og:image:alt | Problem The docs explain what human members are and how they work (pausing, routing, stale reminders), but they don't answer the key question new users ask: When should I add someone as a human mem... |
| og:image:width | 1200 |
| og:image:height | 600 |
| og:site_name | GitHub |
| og:type | object |
| og:author:username | diberry |
| hostname | github.com |
| expected-hostname | github.com |
| None | cc5dfdd32f62ebd3223cab3af3aa2b268d3605218237326a48a99d1efd89495c |
| turbo-cache-control | no-preview |
| go-import | github.com/github/squad git https://github.com/github/squad.git |
| octolytics-dimension-user_id | 9919 |
| octolytics-dimension-user_login | github |
| octolytics-dimension-repository_id | 1151205052 |
| octolytics-dimension-repository_nwo | github/squad |
| octolytics-dimension-repository_public | true |
| octolytics-dimension-repository_is_fork | false |
| octolytics-dimension-repository_network_root_id | 1151205052 |
| octolytics-dimension-repository_network_root_nwo | github/squad |
| turbo-body-classes | logged-out env-production page-responsive |
| disable-turbo | false |
| browser-stats-url | https://api.github.com/_private/browser/stats |
| browser-errors-url | https://api.github.com/_private/browser/errors |
| release | 8c77c9e8439031ad54c75a250694842892f693e1 |
| ui-target | full |
| theme-color | #1e2327 |
| color-scheme | light dark |
| react-app-name | issues |
Links:
Viewport: width=device-width