HiveGrid-Wireframes/hivegrid-cloud/docs/improvement-plan/DETAIL-MD-TEMPLATE.md

Detail-MD Template

Jede Task-Detail-MD MUSS dieser Struktur folgen. Subagents die Detail-MDs erstellen halten sich strikt daran.

# <Task-Title>

**Status:** pending | in_progress | blocked | completed | skipped
**Task-ID:** #<n> (matches TaskCreate ID in conversation history)
**Phase:** <01-11>
**Estimated Effort:** <e.g. 3-5 days>
**Owner:** unassigned (wird vom ausführenden Agent gesetzt)

## Problem

Was ist das Problem? Warum müssen wir es lösen? Welche Codestellen sind betroffen (file:line)?

## Depends on

- `<phase>/<task-file>.md` — Begründung warum dieser Task vorher fertig sein muss
- (weiter wenn nötig)

## Blocks

- `<phase>/<task-file>.md` — was dadurch blockiert ist

## Approach

Ausgewählter Approach mit Begründung (warum nicht die Alternativen). Wenn ein Subagent das implementiert, soll er nicht erneut Architektur-Entscheidungen treffen müssen.

## Implementation Steps

Atomare, nummerierte Schritte. Jeder Schritt soll mit einem atomic commit endbar sein.

1. **Step Title** — was genau passiert
   - Files: `<file-path>` (was wird touched)
   - Commit: `<phase>/<task>: <kurze msg>`
2. **Step Title** — ...

## Test Requirements

Konkrete Test-Spec:

- **Unit-Tests:** welche Funktionen/Klassen müssen getestet sein, welche Cases
- **Integration-Tests:** welche End-to-End-Flows
- **E2E-Tests (Playwright):** wenn UI involviert, welche User-Flows
- **Coverage-Target:** % für den Task-Scope
- **Test-Files:** wo werden sie liegen

Konkrete Anweisung: **NICHT als completed markieren bevor alle Tests grün sind.**

## Acceptance Criteria

Checkliste was Pflicht ist:

- [ ] <konkretes verifizierbares Kriterium>
- [ ] <konkretes verifizierbares Kriterium>
- [ ] Tests grün (lint, typecheck, unit, integration, e2e wenn anwendbar)
- [ ] Doku-File angelegt unter `docs/<feature>.md` (wenn im Task gefordert)
- [ ] Detail-MD Progress Log aktualisiert
- [ ] PROGRESS.md Status auf `completed`

## Rollback Strategy

Wenn dieser Task in Production Probleme verursacht — wie roll-backen?

- Welche Commits revert-bar
- DB-Migrations down?
- Feature-Flag um Funktion zu deaktivieren?

## Security Notes

Was sind die Security-relevanten Aspekte? (Auch wenn der Security-Track separat läuft, manche Tasks haben inhärente Sicherheits-Considerations die mitgedacht werden müssen.)

## Subagent Recommendations

Welche Subagents nutze ich für welchen Schritt?

- **Planning:** `Plan`-Subagent mit Task-Spec als Input
- **Research (wenn nötig):** `Explore` oder `general-purpose` mit konkretem Such-Auftrag
- **Implementation:** `general-purpose` mit klarem Brief, max 1 logischer Schritt pro Subagent
- **Tests:** separater `general-purpose`-Subagent für Test-Schreiben
- **Verification:** `gsd-verifier` oder `general-purpose` für Acceptance-Criteria-Check
- **Code-Review:** `gsd-code-reviewer` nach Task-Completion

## Staging-Deployment-Steps

Wenn der Task externe Services oder Production-ähnliche Validation braucht:

1. Branch `agent/<phase>-<task-name>` pushen
2. Coolify-Auto-Deploy auf staging-instance triggert
3. Smoke-Test-Commands die manuell auf Staging laufen sollen
4. Falls neuer Container/Service: docker-compose-snippet für Staging-Hetzner-Server

## Deviations from Plan

(Wird vom ausführenden Agent während Implementation gefüllt, falls Abweichungen)

## Progress Log

(Wird vom ausführenden Agent nach jedem commit gefüllt)

- YYYY-MM-DD HH:MM — `<commit-sha-short>` — Kurzbeschreibung
- ...

## Lessons Learned

(Optional, am Ende des Tasks für nachfolgende Tasks)

Section-Reihenfolge ist verbindlich

Beim Lesen erwarten ausführende Agents diese Reihenfolge:

1. Frontmatter (Status, Task-ID, Phase, Estimated Effort, Owner)
2. Problem
3. Depends on
4. Blocks
5. Approach
6. Implementation Steps
7. Test Requirements
8. Acceptance Criteria
9. Rollback Strategy
10. Security Notes
11. Subagent Recommendations
12. Staging-Deployment-Steps
13. Deviations from Plan
14. Progress Log
15. Lessons Learned (optional)