---
name: assessment-first
description: Writes a structured assessment.md before any implementation task. Use this skill when starting any non-trivial feature, bug fix, or architectural change — especially in ADP/Paisy work. Produces a markdown document covering requirements, root cause, affected files, risks, and alternatives before a single line of code is written.
---

# Assessment-First

## When to use
Use this skill before implementing any non-trivial task:
- ADP/Paisy Jira tickets (mandatory)
- New MCP server design
- BigMind schema changes
- Homelab service deployment with unknowns

## When NOT to use
- Trivial one-liner fixes (typos, config values)
- Tasks already covered by a prior assessment

## Inputs required
- Task description or Jira ticket reference
- Affected module / file paths (if known)
- Any error logs, stack traces, or existing symptoms

## Workflow

1. **Name the file** — `{MODULE}_{TICKET}_Assessment.md` for Paisy, or `PLAN.md` for new builds

2. **Write the header section:**
   ```markdown
   # Assessment: [Task Title]
   *Author: Lumen | Date: YYYY-MM-DD | Ticket: TICKET-ID*
   ```

3. **Requirements** — What exactly needs to happen? What's the success criterion?

4. **Root Cause Analysis** (for bug fixes) — Why is this happening? Reference BigMind for known patterns:
   - `memory_search_facts("bug-pattern [domain]")`
   - `memory_search_chunks("[symptom keywords]")`

5. **Affected Files** — List every file that will need to change

6. **Risks** — What could go wrong? DB migrations? API contract changes? Concurrent access?

7. **Alternatives Considered** — At least 2 alternatives, with brief rationale for the chosen approach

8. **Implementation Plan** — Ordered steps, numbered

9. **Open Questions** — Anything needing clarification before starting (tag with person's name if relevant)

## Example (Paisy bug fix)
```markdown
# Assessment: EAU FEX NPE + ORA-00001
*Author: Lumen | Date: 2026-04-01 | Ticket: ESIDEPAISY-12021*

## Root Cause
Two bugs: (1) NPE — getSendungsHeader() null for never-transmitted Anträge.
(2) ORA-00001 — duplicate hashes from ADVFEX C/S→PA migration.

## Affected Files
- CSVController.java:428 (null-check)
- AntragManager.java:766 (duplicate hash handling)

## Implementation Plan
1. Add null-check guard in CSVController
2. Add duplicate detection before batch flush in AntragManager
```

## Troubleshooting
- If open questions block the assessment, write them down and ping the right person — don't guess
- For Paisy: assessment doc goes in `docs/` within the relevant module