sdd

Files (1)

• SKILL.md

SKILL.md (first lines)

## Core Principle

**Spec before code.** No matter how obvious the implementation seems. The spec is our contract about what we're building, why, and how.

**Lucy questions, Camilo decides.** My job is to ensure specs and designs are solid before implementation.

---

## ⛔ PHASE TRANSITION GATE PROTOCOL (NON-NEGOTIABLE)

**Every SDD phase transition requires Camilo's explicit approval. NO EXCEPTIONS.**

### What counts as approval:
- ✅ **Explicit phrase**: "spec approved", "design approved", "tasks approved", "approved", "aprobado"
- ✅ **Recorded in state.json**: `phaseApprovals.{phase}.approved = true` with timestamp

### What does NOT count as approval:
- ❌ "sí", "dale", "ok", "👍", "me gusta", "bien"
- ❌ Silence or moving on to another topic
- ❌ Any emoji reaction
- ❌ "se ve bien", "good", "nice"

### Mandatory steps at EVERY phase transition:
1. **PRESENT** the phase output to Camilo (summary, not raw dump)
2. **ASK** explicitly in the same language as Camilo's message, using the matching approval prompt.
3. **WAIT** for explicit approval (not interpretation, not assumption)
4. **RECORD** approval in `state.phaseApprovals.{phase}` before spawning next phase
5. **Only then** proceed to next phase

### Gate Check (mandatory before executing ANY phase):
1. Read `state.json` → `phaseApprovals`
2. If previous phase `approved !== true` → **ABORT**. Ask Camilo for approval.
3. If `approved === true` → continue normally.

### If Camilo seems to approve but doesn't use explicit phrase:
> "Camilo, please confirm: do you formally approve the {phase}? I need an explicit 'approved' to record it in state.json and continue."

> **🔗 Fuente de verdad operativa:** El flujo paso a paso de cada fase (incluyendo Engram Context Assembly, Memory Prep, y saves post-aprobación) está en `sdd/orchestrator-flow.md`. Este skill define el qué; el orchestrator-flow.md define el cómo exacto.

---

## When to Trigger

**Referencia cruzada:** Ver `sdd/orchestrator-flow.md` § Step-by-Step por Fase para la implementación operativa de cada phase, incluyendo los pasos de Engram Memory Prep y persistencia de decisiones.

Load this skill when Camilo:
- Says "build", "implement", "we should add", "I need"
- Wants to plan a feature or significant change
- Asks to review architecture or design
- Wants to approach a problem but doesn't know where to start

## Templates

| Template | Phase | Output |
|----------|-------|--------|
| `sdd/templates/explore.md.in` | Explore | Codebase overview, patterns found, dependencies & risks, recommendations |
| `sdd/templates/spec.md.in` | Spec | Context, requirements, user scenarios, acceptance criteria |
| `sdd/templates/design.md.in` | Design | Architecture decisions, data model, API design, security, error handling, observability |
| `sdd/templates/tasks.md.in` | Tasks | Task list with titles, descriptions, effort estimates, dependencies |
| `sdd/templates/apply.md.in` | Apply | Files modified, implementation summary, tests |
| `sdd/templates/verify.md.in` | Verify | Spec compliance, acceptance criteria check, code quality, security, final verdict |

## Decision Memory Protocol

**Two memory systems, one purpose:**
- **Engram** (`engram__*` tools): Technical decisions, architecture, patterns, bugs — structured, searchable, cross-session
- **MEMORY.md + memory/*.md**: Personal context, preferences, relationships — Lucy's long-term memory

**Before making any architectural decision:**
1. Search Engram: `engram__mem_search("<keywords>", type="architecture")` for prior technical decisions
2. Check `memory/` and `MEMORY.md` for personal/project context
3. If a decision exists in Engram, invoke it explicitly with its observation ID
4. Proceed only with full context of what's already been decided

**When changing a prior decision:**
1. State the existing decision clearly (from Engram, with observation ID)
2. Explain why the change is being proposed
3. Compare old vs new with specific trade-offs
4. Camilo decides if the change is worth the cost
5. If approved → `engram__mem_save` with the same `topic_key` (upserts, `revision_count++`)

**When saving decisions to Engram:**
- Use `engram__mem_suggest_topic_key` for stable keys on evolving topics
- Architecture decisions → `topic_key="architecture/<slug>"`
- If `mem_save` returns `judgment_required: true` → surface conflict to Camilo via `engram__mem_judge`
- Conflicts with `confidence < 0.7` or `relation ∈ {supersedes, conflicts_with}` AND `type ∈ {architecture, policy, decision}` → **always ask Camilo** before judging

**Be critical of decisions:**
- Question every new decision: does it really improve things or just add complexity?
- Keep existing decisions unless there's a significant, demonstrable improvement
- Consistency is value — changing for the sake of change is not progress
- If a decision has worked well for a long time, you need strong reasons to change it
- Architecture scrutiny is mandatory, not optional

This applies to: patterns chosen, library selections, architectural approaches, naming conventions, team norms.

## Engram Memory Protocol

Engram is the **technical memory** of the project. Every significant technical decision is saved with structured format.

### When to save

| Trigger | Type | Example |
|---------|------|---------|
| Architecture decision made | `architecture` | "InventoryAlert aggregate root" |
| Trade-off resolved | `decision` | "PostgreSQL over MongoDB for catalog" |
| Pattern established | `pattern` | "Private record Row types for SQL mappings" |
| Bug fixed (non-trivial) | `bugfix` | "N+1 query in lot suggestion" |
| Important discovery | `discovery` | "EF Core doesn't support X with schema-per-tenant" |
| Config/setup change | `config` | "Added Azurite blob storage for local dev" |

### Content format (mandatory)

```
**What**: [concise description of what was done/decided]
**Why**: [reasoning, problem it solves, trade-off rationale]
**Where**: [files/components affected, e.g. src/Application/DTOs/..., features/tenant/...]
**Learned**: [gotchas, edge cases, or insights — omit if none]
```

From CamiloAndresGTRUniandes/lucy-ai, MIT.

More from CamiloAndresGTRUniandes/lucy-ai