[Feature]: /speckit.assign — human-judgment detection, confidence scores, and dependency awareness

[SteeZyT33]

Problem Statement

During a real-world 75-task spec execution (cleanup, CI/CD & release pipeline), /speckit.assign required two passes to get assignments right. The first pass assigned branch triage tasks (deciding whether to merge/close/salvage PRs) to [@DevOps Automator] because "diff branch X against main" matches DevOps keywords syntactically — but these were actually human judgment calls requiring decisions about content value, conflict resolution, and salvage strategy.

71% of the work in Phase 2 (branch content audit) and Phase 3 (branch cleanup) was fundamentally human decision-making, not automatable agent work.

Proposed Solution

1. Built-in [@Human] agent type

Add [@Human] (or [@Human Lead]) as an internal agent in the Tier 1 agent table. Trigger on keywords indicating judgment complexity:

Keywords	Signal
triage, decide, evaluate, choose between	Decision required
audit for value, salvage or discard	Content judgment
merge vs close, keep or delete	Binary judgment on external input
review conflicting, resolve conflict	Conflict resolution
approve, sign off	Authority gate

2. Confidence scores per assignment

Show a confidence score based on keyword overlap strength. When score < 0.3 (weak match), suggest [@Unassigned] or [@Human] instead of forcing the best-available agent.

Example output:

| Task | Agent | Confidence | Note |
|------|-------|-----------|------|
| T003 | [@Human] | 0.85 | "triage" + "decide" detected |
| T047 | [@Security Engineer] | 0.92 | strong keyword match |
| T015 | [@DevOps Automator] | 0.18 | weak match — suggest human |

3. Dependency awareness

Read the dependency section of tasks.md. When task B depends on task A and they're assigned to different agent types, flag the handoff cost. This helps identify codependent tracks that should share an assignee.

4. --human-tasks flag

Allow pre-marking specific tasks for human assignment before auto-assignment runs:

/speckit.assign --human-tasks "T003-T009"

Cleaner than passing prose in the --reassign-all instruction string.

5. Phase context weighting

The phase heading is a strong signal the skill underuses:

• "Foundational — Branch Content Audit" → strongly weight toward [@Human]
• "Setup" → weight toward [@DevOps Automator]
• "Polish & Cross-Cutting" → weight toward [@Evidence Collector] / [@Technical Writer]

Alternatives Considered

• Manual-only assignment: Works but defeats the purpose of the skill
• Per-task --agent override: Too granular — --human-tasks with range syntax is better
• LLM-based task classification: More accurate but slower and model-dependent; keyword heuristics with confidence scores are a reasonable middle ground

Component

Spec templates (BDD, Testing Strategy, etc.)

AI Agent

All agents

Use Cases

1. When a spec involves branch triage, PR review, or merge/close decisions — these are fundamentally human judgment tasks that should not be auto-assigned to technical agents
2. When tasks are codependent across tracks — e.g., "cleanup needs good DevSecOps, DevSecOps needs clean branches" — dependency awareness surfaces the coupling
3. When confidence is low on an assignment — better to flag [@Unassigned] than silently assign a poor match and discover it during implementation

Acceptance Criteria

• [@Human] or equivalent is available as an internal agent type
• Keyword-based judgment detection triggers human assignment for triage/decision tasks
• Assignment output includes a confidence indicator (numeric or categorical)
• --human-tasks flag (or equivalent) allows pre-marking tasks before auto-assignment
• Phase heading text influences agent selection weighting
• Dependency warnings when dependent tasks are assigned to different agent types

Additional Context

Field report from perf-lab Spec 1 (002-cleanup-cicd-release): 75 tasks, 9 phases, two parallel tracks. First /speckit.assign pass was wrong enough that --reassign-all was needed immediately. The reassignment instruction had to be passed as prose in the flag args: --reassign-all — The branch cleanup phases (Phase 2, Phase 3/US1) require human judgment for triage decisions on conflicting content. Assign those to [@Human Lead] with agent support. The rest stays agent-assignable.

Source file: templates/commands/assign.md

[mnriem]

Please consider creating a Spec Kit extension for this. See https://github.com/github/spec-kit/tree/main/extensions