---
name: ao-impl-details
description: "Extract, plan, or propose implementation details at configurable depth levels (low/normal/extensive). Outputs to reference files for team discussion and handoff."
category: extended
invokes: [ao-state]
invoked_by: [ao-planning, ao-implementation]
state_files:
  read: [focus.json, issues/*.md, issues/references/*]
  write: [focus.json, issues/references/*]
reference: [REFERENCE.md]
---

# Implementation Details

Generate detailed implementation specifications at varying depths.

**Reference**: See [REFERENCE.md](REFERENCE.md) for templates, examples, and output formats.

---

## Depth Levels

| Level | Name | Includes | Use Case |
|-------|------|----------|----------|
| 1 | `low` | Files, approach, dependencies, risks | Quick alignment |
| 2 | `normal` | + Signatures, pseudo-code, data structures | Technical review |
| 3 | `extensive` | + **Actual executable code**, edge cases, tests | Formal spec |

### Auto-Selection by Confidence

| Confidence | Level | Override |
|------------|-------|----------|
| LOW | **extensive** (mandatory) | No |
| NORMAL | normal | Yes |
| HIGH | low | Yes |

**LOW confidence requires extensive details with actual executable code.**

---

## Modes

### Extract Mode
Document existing code to understand how it works.

**Input**: File path or symbol name

**Procedure**:
1. Identify target (file or symbol)
2. Analyze at requested level
3. Generate reference file: `.agent/ops/issues/references/{context}-impl-extract.md`

### Plan Mode
Generate implementation details for planned changes.

**Input**: Issue ID (e.g., `FEAT-0083@c5f3e7`)

**Procedure**:
1. Read issue requirements and acceptance criteria
2. Analyze affected code
3. Generate details at requested level
4. Create reference file: `.agent/ops/issues/references/{ISSUE-ID}-impl-plan.md`
5. Link from issue's `spec_file` field

### Propose Mode
Suggest implementation approach for a conceptual change.

**Input**: Description of desired change

**Procedure**:
1. Identify affected areas
2. Generate approach options
3. Create proposal file: `.agent/ops/issues/references/{context}-impl-proposal.md`

---

## Output Sections

All levels include:
- **Summary**: One-paragraph overview
- **Files Affected**: Table of files and actions
- **Approach**: Technical rationale
- **References**: reference all external reference identifiers, like Jira issues, UX designs, Gherkin features, Github issues/PRs

Normal adds:
- **Detailed Changes**: Function signatures, code locations
- **Dependencies**: What this requires/enables
- **Risks**: Potential issues with mitigations

Extensive adds:
- **Per-File Traceability** (MANDATORY): Each file MUST have a "Requirements Source" section linking to specific Gherkin scenarios, user stories, UX designs,or specs that justify its creation/modification
- **Complete Implementation**: Full executable code
- **Edge Cases**: Table of cases and handling with test coverage status
- **Test Cases**: Complete test functions

---

## Per-File Traceability (Extensive Level — MANDATORY)

**Every file in an extensive plan MUST have explicit traceability to requirements.**

This is NOT optional. If no requirement source exists, document "Derived from: {parent requirement}" or "Technical necessity for: {reason}".

### Required Format for Each File

```markdown
### File: `path/to/file.cs`

**Requirements Source**:
- Gherkin: `Features/MyFeature.feature` — Scenario "User can do X"
- User Story: JIRA-123 — "As a user, I want..."
- Derived from: {parent file} — needed for {reason}

**Fields/Logic Derived From**:
| Field/Method | Source | Traceability |
|--------------|--------|-------------|
| `ServiceName` | Gherkin table column "Navn" | `VisTjenester.feature:12` |
| `Validate()` | AC-3: "Must validate before save" | JIRA-123 |

**Code**:
```csharp
// Full implementation
```
```

### Why This Matters

1. **Auditability**: Reviewers can verify implementation matches requirements
2. **Traceability**: Changes to requirements can be traced to affected code
3. **Prevents drift**: Implementation can't diverge from documented requirements
4. **Onboarding**: New team members understand WHY code exists

---

## Invocation

```bash
# Extract existing code
/ao-impl-details extract src/services/auth.ts --level normal

# Plan for issue
/ao-impl-details plan FEAT-0083@c5f3e7 --level extensive

# Propose approach
/ao-impl-details propose "Add rate limiting to API" --level low
```

---

## Confidence Indicators

Output should include:

```markdown
## Confidence Indicators

### ✅ High Confidence
- All files identified
- Clear API contracts

### ⚠️ Uncertainty
- {Area}: {Why}

### ❓ Blockers
- {Question needing answer}
```
