| name | retrospective |
| description | Structured post-work retrospective for Home Assistant Homelab: review outcomes, mine git history for context drift, classify lessons, and route improvements — HA-local vs contribute back to prime-context. Use when the user says retro, /retrospective, what did we learn, or at session-end. |
| disable-model-invocation | true |
Retrospective — Home Assistant Homelab
A structured review at work-close or session-end. The retrospective
classifies observations and routes them: local context edits,
HA-domain skill/rule improvements, or upstream contributions to
prime-context.
This skill does not edit files directly (except optional non-protected scratch
notes). It produces a report with classified recommendations. Protected-path
edits go through confirmation (protected-paths.md).
Git is operator-owned (operator-owned-git.md)
— no PR automation, no commits from this skill. This repo does not use git
worktrees; inspect the main checkout.
When to run
- After a meaningful config /
.agents/ change set (before the operator commits)
- At session-end when the operator asks "what did we learn?"
- After merges or Syncthing syncs that changed context surfaces outside the session
- Standalone:
/retrospective or "do a retro"
There is no required ship-work / clock-out gate here. Retrospectives inform;
they do not block.
What it produces
- Outcome summary — what happened, one or two lines
- Git history findings — significant changes that touched context surfaces
- Observations — classified lessons, each with a route
- Upstream candidates — generic enough for prime-context
- HA-local keepers — packages conventions, shopping-list rules, domain skills
- No-op declaration — if nothing to capture, say so explicitly
Workflow
- [ ] 1. Scope the retrospective
- [ ] 2. Review the session's own work
- [ ] 3. Mine git history for external changes
- [ ] 4. Classify observations
- [ ] 5. Assess genericness (upstream vs HA-local)
- [ ] 6. Route and propose actions (no auto-PR)
- [ ] 7. Propose durable lessons (memories / rules — after confirm)
- [ ] 8. Report
1. Scope
| Situation | Window |
|---|
| End of a change set | This session's diff + discussion |
| Session-end (no edits) | This session |
| After external merges | Since last session (or last N commits on main) |
| Operator names a range | That PR/date/branch |
2. Review the session's own work
- What happened vs what was planned?
- What worked / failed / needed retries?
- Did any rule feel wrong, missing, or redundant?
- Did context modules or HA skills mislead or leave gaps?
If nothing happened, say so and continue to git history.
3. Mine git history
git log --oneline --since="<last session date or tag>" -- \
AGENTS.md CLAUDE.md .agents/ packages/ docs/ esphome/
Optional if gh is available — do not require it. For each significant change:
what changed, why (commit body), context impact.
Significant here: new package category conventions, renamed packages,
ESPHome ownership shifts, .agents/ edits, shopping-list / work-sources rules,
validation script changes.
4. Classify
| Type | Example | Route |
|---|
| Context drift | traps.md describes a pattern packages no longer use | reconcile-context |
| Context gap | No guidance for a new subsystem | Propose context edit (protected) |
| Context bloat | Unused module | Propose trim |
| Rule gap | Convention violated with no rule | Propose rule |
| Skill gap | HA skill missed a step | Propose skill edit |
| Enforcement gap | Protected-path confirm skipped repeatedly | Propose hook/CI |
| Pattern / anti-pattern | Repeated success or failure | Record; consider promotion |
5. Upstream vs HA-local
| Test | Result |
|---|
| Touches HA packages, entities, shopping list, ESPHome, live validate-before-commit | HA-local |
| Improves generic rules/skills/scripts usable by other prime-context consumers | Upstream candidate |
Layer 3 context / HA-native skills (automation-debug, config-validate, package-organize) | HA-local |
| Layer 1–2 shared skills/rules/scripts | Consider upstream |
Upstream candidates: propose an issue description or patch notes for the
operator to take to the prime-context repo. Do not open PRs or push to
prime-context from this skill unless the operator explicitly asks.
6. Route and propose
| Route | Action | Approval |
|---|
| reconcile-context | Note drift for next pass / run skill | Skill handles |
| Context / rule / skill edit | Propose diff in report | Yes (protected) |
| Enforcement | Propose hook/CI | Yes |
| Memory | Propose .agents/memories/<topic>.md | Yes |
| Upstream | Draft contribution notes for operator | Yes — operator owns git on prime-context |
| Shopping-list wording | Suggest title for operator to add in HA | Never write the file |
7. Durable lessons
Propose lessons for .agents/memories/<topic>.md (Context / Lesson /
References). Always-on policy belongs in a rule, not memories. Promotion path:
Memory → recurs 3+ times → Rule → fails repeatedly → Hook
8. Report
## Retrospective
**Scope:** …
**Outcome:** …
**Git history findings:** <N or none>
- …
**Observations:**
| # | Type | Observation | Route | Action |
| --- | ---- | ----------- | ----- | ------ |
| 1 | … | … | … | … |
**Upstream candidates (prime-context):** <N or none>
- … → draft for operator (no PR automation)
**HA-local keepers:** <N or none>
- …
**Memories proposed:** <N or none>
**Needs human judgment:**
- …
Do not
- Commit, push, or open PRs
- Edit protected paths without confirmation
- Skip the git history pass
- File upstream contributions without evidence
- Auto-run ship-work / clock-out / self-improve shipping loops
- Expand into implementation — recommendations only
- Write
.shopping_list.json
