/learn-review

name: learn-review
description: Review spaced-repetition facts that are due today. Applies SM-2 algorithm to update interval, ease, and next_review in each fact's frontmatter. Updates review-log.jsonl. Use when the user says "revisar", "review facts", "study", or "/learn-review".

Learn Review

Reviews facts in `workspace/learning/facts/` whose `next_review` date is today or in the past. Applies SM-2 grading and rewrites frontmatter in-place. Records every grade in `workspace/learning/.state/review-log.jsonl`.

SM-2 Formula (implement exactly as specified)

Given current `reps`, `interval`, `ease`, `lapses`:

**Again (grade 0):**

• `reps = 0`
• `interval = 1`
• `ease = max(1.3, ease - 0.2)` (round to 2 decimal places)
• `lapses = lapses + 1`

**Hard (grade 3):**

• `interval = round(interval * 1.2)` (minimum 1)
• `ease = max(1.3, ease - 0.15)` (round to 2 decimal places)
• `reps = reps + 1`

**Good (grade 4):**

• If `reps == 0`: `interval = 1`
• Else if `reps == 1`: `interval = 6`
• Else: `interval = round(interval * ease)` (minimum 1)
• `ease` is unchanged
• `reps = reps + 1`

**Easy (grade 5):**

• Same interval as Good, then additionally: `interval = round(interval * 1.3)` (minimum 1)
• `ease = ease + 0.15` (round to 2 decimal places)
• `reps = reps + 1`

**For all grades:** `next_review = review_date + interval days`

**Ease floor:** 1.3. Never let ease drop below 1.3 regardless of how many Again grades.

Workflow

Step 1 — Scan for due facts

1. Read all `.md` files in `workspace/learning/facts/` 2. Parse the frontmatter of each file 3. Get today's date (YYYY-MM-DD) 4. Select facts where `next_review <= today` 5. Sort by `next_review` ascending (oldest due first) 6. Take up to 5 facts (N=5 default)

If no facts are due: > "Nenhum fato vencido hoje. 🎉 Próxima revisão: {earliest next_review across all facts}." > Stop here.

If `workspace/learning/facts/` does not exist or is empty: > "Nenhum fato encontrado. Use /learn-capture para adicionar fatos primeiro." > Stop here.

Step 2 — Review loop (one fact at a time)

For each due fact (up to 5):

**2a. Show the question:**

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📚 Deck: {deck} | Fato {current}/{total_due_shown}
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
❓ {Retrieval Q content}

[Pense na resposta antes de prosseguir. Pressione Enter quando pronto.]

Wait for the user to confirm they've thought about it (any input is fine).

**2b. Show the answer:**

✅ Resposta:
{Fact content}

💡 Por quê importa:
{Why it matters content}

**2c. Ask for grade:**

Como foi? 
  0 - Again  (errei / não lembrei)
  3 - Hard   (lembrei com dificuldade)
  4 - Good   (lembrei bem)
  5 - Easy   (muito fácil)

Wait for the user to enter 0, 3, 4, or 5. Accept also the words "again", "hard", "good", "easy" (case-insensitive).

Step 3 — Apply SM-2 and update file

For the grade received:

1. Compute `prev_interval = current interval` 2. Compute `prev_ease = current ease` 3. Apply SM-2 formula above to get `new_interval`, `new_ease`, `new_reps`, `new_lapses` 4. Compute `new_next_review = today + new_interval days` 5. Rewrite the fact file with updated frontmatter, preserving the body content exactly

**Frontmatter rewrite rules:**

• Update only: `next_review`, `interval`, `ease`, `reps`, `lapses`
• Preserve all other fields unchanged: `id`, `source`, `deck`, `created`
• Preserve the body (everything after the closing `---`) exactly as-is

Step 4 — Append to review log

Append one JSON line to `workspace/learning/.state/review-log.jsonl` (create file if it doesn't exist, create directory if needed):

{"ts": "{ISO8601_timestamp}", "fact_id": "{id}", "grade": "{again|hard|good|easy}", "prev_interval": {N}, "new_interval": {M}, "prev_ease": {X}, "new_ease": {Y}}

Grade string mapping: 0→"again", 3→"hard", 4→"good", 5→"easy"

Step 5 — Next fact

Continue with the next due fact. After all N facts (or all due facts if < N):

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✅ Sessão de revisão concluída!
Revisados: {N} fatos
Resultado: {X} Good/Easy | {Y} Hard | {Z} Again
Próxima revisão: {earliest next_review across all facts}
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Verification helper (Grade Good progression)

When testing, the interval sequence for repeated Good grades starting from `reps=0, interval=1, ease=2.5`:

| Review | Grade | reps before | interval before | → reps after | → interval after | |--------|-------|-------------|-----------------|--------------|-----------------| | 1st | Good | 0 | 1 | 1 | 1 | | 2nd | Good | 1 | 1 | 2 | 6 | | 3rd | Good | 2 | 6 | 3 | 15 (round(6*2.5))|

Constraints

• Max N=5 facts per session. If more are due, the user can run again.
• ONLY update files in `workspace/learning/facts/` and `workspace/learning/.state/review-log.jsonl`.
• Do NOT modify `deck` metadata files or any file outside these two locations.
• Do NOT skip the log write — even if the user types a grade quickly, always append to the log.
• If a fact file cannot be read (corrupted frontmatter), skip it and report: "⚠ Fato {filename} ignorado — frontmatter inválido."