Reasoning Explainability

Guidelines for making SDD agent reasoning auditable and traceable.

Two complementary mechanisms:

1. Reasoning Log: Structured record of decisions made by an agent during its execution.
2. Handoff Envelope: Structured context passed from one agent to another during handoff.

Reasoning Log

Upon completing execution and before creating artifacts, present the user with a summary of decisions made.

Reasoning Log Format

## Reasoning

### Decisions

| # | Decision | Applied principle | Alternatives considered | Justification | Confidence |
|---|----------|-------------------|------------------------|---------------|------------|
| 1 | [what was decided] | [principle or heuristic that guided the choice] | [discarded options] | [why this choice] | [High/Medium/Low] |

### Assumptions

- [assumption made and basis for it]

### Missing information

- [data that was missing and how it impacts the decisions above]

"Applied principle" column

Connects each decision to the reusable foundation that guided it. The goal is to make engineering judgment visible — not just what was decided, but what reasoning pattern was used.

Examples of principles:

Rules:

• Fill in only when the principle is not obvious from the justification. If the justification already contains the rationale, use "—".
• Use direct language, not academic jargon. "Fail-fast to detect errors early" is better than "Application of the rapid failure principle per the defensive paradigm".
• Project principles (defined in coding-guidelines.md or ADRs) take priority over generic industry principles.

Confidence Levels

Reasoning Log Rules

• Trivial decisions (formatting, already established conventions) do not need to be recorded.
• For Medium or Low confidence, include what is needed to raise the level.
• If there were no significant decisions, omit the section (do not force reasoning where none exists).
• Keep it concise: 3-8 decisions per execution is expected. If there are more, group related decisions.

Handoff Envelope

When performing a handoff to another agent, include a structured context block along with the handoff prompt.

Handoff Envelope Format

### Handoff Context

**Relevant artifacts**: [list of files the next agent should read]
**Inherited assumptions**:
- [assumption the upstream agent made that influences the downstream]

**Pending decisions** (for the next agent to resolve):
- [decision that was left open and why]

**Discarded information**:
- [context or alternative that was considered and discarded, with reason]

Handoff Envelope Rules

• Include only information that impacts the next agent's work. Do not repeat what is already in the artifacts.
• If there are no inherited assumptions or pending decisions, omit those subsections.
• The envelope complements (does not replace) the user's original input.

Application by Agent Type

Agents that produce persistent artifacts

devsquad.envision, devsquad.kickoff, devsquad.specify, devsquad.plan, devsquad.decompose, devsquad.implement, devsquad.security

• Present Reasoning Log before creating/saving artifacts.
• The user can question decisions before they become artifacts.

Analysis agents (read-only)

devsquad.sprint, devsquad.refine

• Integrate reasoning inline in the analysis (e.g., "Classified as 'Not ready' because [evidence]").
• Do not use a separate section; the reasoning is the output itself.

Conductor

devsquad

• When the intent is not obvious (multiple agents could handle it), briefly document the rationale:

  Interpreted "[input]" as [intent] because [reason].
  Delegating to [agent].

• When the intent is clear, do not add overhead — delegate directly.