Skip to content

Docs: Add decision framework for when to add human members #313

Closed

Description

@diberry

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 came up during onboarding — the distinction between a casual contributor and a roster-listed human isn't documented anywhere.

What's missing

Decision framework (the litmus test)

  • 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)
  • Don't add when the person is a collaborator you interact with through normal GitHub flows — commenting on PRs, reviewing code, filing issues

Specific gaps across docs

Question Current coverage
When should I add a human vs. @mention them? Not addressed
Casual contributors vs. roster members? Not addressed
What if I have 20 people — do all go on roster? Not addressed
Solo project — should I roster myself? Not addressed

Where this guidance should live

  1. .squad/templates/human-members.md — the authoritative template (see companion issue for creating this file)
  2. docs/src/content/docs/features/human-team-members.md — user-facing docs page
  3. docs/src/content/docs/concepts/your-team.md — team composition overview

Proposed decision framework

Add a section like:

When to add a human member

Scenario Add to roster? Why
Approves architecture decisions before implementation ✅ Yes Decision gate — team should route and wait
Reviews all docs PRs as a standing reviewer ✅ Yes Recurring review gate
Occasionally reviews PRs when tagged ❌ No Use @mention on the PR
Files issues and contributes code ❌ No Normal GitHub collaboration
Makes final ship/no-ship call ✅ Yes Approval gate

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.

Acceptance criteria

  • Decision framework added to human-team-members.md docs page
  • Brief mention added to your-team.md (link to full framework)
  • Template file includes the framework (if created — see companion issue)

Activity

  1. diberry commented on Mar 9, 2026

    @diberry
    ContributorAuthor

    cc @bradygaster — decision framework for when to add humans. Companion to #312. Both need squad:pao labeling for the docs agent.

  2. added a commit that references this issue on Mar 9, 2026
    be1e7d9
  3. added a commit that references this issue on Mar 10, 2026
    bbceec3
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions