github / github/spec-kit

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

Open
#2,053 2 comments 0 reactions 0 assignees View on GitHub
stale
Dominant language
Python
Stars
137k
Forks
12.3k
Avg merge
2d 7h
Merged PRs (30d)
155

Description

## 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`

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.