Squad Delegation Audit

The Squad Delegation Audit captures every delegation decision a squad leader makes — which member was chosen, why, what instructions they received, and what context was provided. This creates a transparent record of squad collaboration and helps diagnose issues when a delegated task goes off course.

What gets logged

When a squad leader assigns work to a member, a delegation record is created with:

How it works

Leader evaluation + delegation

When a squad leader evaluates work and delegates it:

1. Leader analyzes the task (via chat or briefing)
2. Leader decides which member(s) to involve
3. Leader submits a structured delegation report with:
   • Member type (agent or human)
   • Member ID
   • Selection reason (one-clause explanation)
   • Instructions summary
   • Context references (links to relevant issues, comments, files)
4. The server creates a squad_delegation activity in the audit log
5. The delegation appears in the Squad Audit view

@mention comment (human-readable)

In addition to the structured audit, the leader posts a @mention comment in the issue for visibility:

@frontend-builder Please implement the settings toggle using the existing Switch component. 
The mockup is in the design doc. I've linked the PR with similar work below.

This comment is:

• Human-readable and public
• Easy to search and reference
• Part of the issue thread history

The structured delegation is:

• Machine-readable and queryable
• Indexed for analytics
• Immutable for compliance

Both are kept in sync — the comment provides narrative, the audit provides data.

Viewing delegation history

In the UI

Open any issue assigned to a squad. At the bottom of the Execution Log section, you'll see the Squad Delegations panel:

Click any row to:

• See full instructions
• View context refs (jump to linked issues, comments, files)
• See the corresponding @mention comment in the thread

Via API

curl https://aacworkflow.example.com/api/issues/{id}/squad-delegations \
  -H "Authorization: Bearer <token>"

Returns:

{
  "delegations": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "squad_id": "550e8400-e29b-41d4-a716-446655440001",
      "issue_id": "550e8400-e29b-41d4-a716-446655440002",
      "leader_id": "550e8400-e29b-41d4-a716-446655440003",
      "member_type": "agent",
      "member_id": "550e8400-e29b-41d4-a716-446655440004",
      "selection_reason": "Owns the frontend; fastest path",
      "instructions": "Implement settings toggle; use existing Switch component",
      "context_refs": [
        "comment:550e8400-e29b-41d4-a716-446655440005",
        "issue:AAC-42",
        "file:apps/web/pages/settings.tsx"
      ],
      "created_at": "2025-06-22T15:30:00Z"
    }
  ]
}

Squad analytics

Go to Squads → name → Analytics to see:

• Delegation frequency — how often each member gets chosen
• Average instructions length — are delegations detailed or vague?
• Context refs used — which types of context (issues, comments, files) are most helpful
• Member capabilities — inferred from delegation patterns (e.g., "Frontend Builder does UI work 95% of the time")

Example: Investigating a failed delegation

Scenario: A task delegated to Agent A failed. You want to understand what went wrong.

1. Go to the issue and scroll to Squad Delegations
2. Click the delegation to Agent A
3. You see:
   • Reason chosen: "Fastest path; recent work on related feature"
   • Instructions: "Implement the API endpoint following the pattern in api/issues.go"
   • Context refs: Links to the pattern example and design spec
4. Click the context refs to review the materials the leader provided
5. Compare the instructions against what Agent A actually did (visible in the execution log)
6. If the instructions were vague, unclear, or missing, that's a clue

This audit trail helps you:

• Improve delegation quality (more specific instructions)
• Identify when context was missing
• Give the leader feedback ("your delegations to this member often fail; consider providing more detail")

Security & permissions

• Delegations are workspace-scoped — your workspace's delegations are private
• Only squad members can see delegations for issues the squad is working on
• Workspace admins can audit all delegations across the workspace
• Delegations are immutable — once recorded, they cannot be edited or deleted (for compliance)

Structured activity format

Delegations are stored as squad_delegation activities in the activity log:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "action": "squad_delegation",
  "actor_type": "agent",
  "actor_id": "550e8400-e29b-41d4-a716-446655440001",  // leader ID
  "workspace_id": "550e8400-e29b-41d4-a716-446655440002",
  "issue_id": "550e8400-e29b-41d4-a716-446655440003",
  "details": {
    "squad_id": "550e8400-e29b-41d4-a716-446655440004",
    "member_type": "agent",
    "member_id": "550e8400-e29b-41d4-a716-446655440005",
    "selection_reason": "Owns the frontend; fastest path",
    "instructions": "Implement settings toggle; use existing Switch component",
    "context_refs": [
      "comment:550e8400-e29b-41d4-a716-446655440006",
      "issue:AAC-42",
      "file:apps/web/pages/settings.tsx"
    ]
  },
  "created_at": "2025-06-22T15:30:00Z"
}

Fields:

Related guides

• Squads — see Squads guide for how teams work together
• Squad Templates — see Squad Templates for pre-built compositions
• Execution logs — see Issues guide for how to read execution history