Algernon Review

FSRS-4.5 flashcard review session for OpenAlgernon. Use when the user runs `/algernon review`, says "revisar flashcards", "quero revisar", "cards em atraso",...

Security Scan

The skill's instructions are consistent with a local flashcard review tool that reads and updates a local SQLite database, but there are a few practical mismatches and minor safety notes you should be aware of before installing.

Purpose & Capability

The skill is described as a local FSRS-based review session and all runtime instructions operate on a local SQLite DB (default: $ALGERNON_HOME/data/study.db), which is coherent with the purpose. However the SKILL.md depends on the sqlite3 command-line tool being available, yet the registry metadata lists no required binaries — this is an omission in the metadata (the skill will fail or cannot run without sqlite3).

Instruction Scope

The instructions explicitly run SQL SELECT/UPDATE/INSERT against a local DB and direct creation of 'correction' cards. This is expected for a flashcard reviewer, but it means the agent will read and write all card content in the database (private user data). The SQL snippets insert unsanitized values (e.g., DECK_ID, MISCONCEPTION_QUESTION, CORRECT_EXPLANATION) which could cause accidental corruption or SQL injection if variables are not validated; there is no guidance in SKILL.md about sanitization or safe parameter binding.

Install Mechanism

Instruction-only skill with no install steps or external downloads — lowest install risk. Nothing is written to disk by an installer.

Credentials

No required environment variables or credentials are declared, which matches the skill being local. The instructions do reference ALGERNON_HOME (optional) and $HOME, so the skill will read files under the user's home directory; this is appropriate for a local study DB but should be made explicit in metadata (e.g., declare that it needs filesystem access to ~/.openalgernon).

Persistence & Privilege

The skill does not request always:true and does not modify other skills or global agent settings. It performs only its own DB reads/writes during a session, which is expected behavior.

Assessment

This skill appears to be what it says: a local FSRS review agent that reads and updates an SQLite database. Before installing, be aware of these points: - The skill expects sqlite3 on PATH but the metadata doesn't declare it; install sqlite3 or ensure your runtime includes it. The skill will fail without it. - It will read and write your flashcard DB (default ~/.openalgernon/data/study.db). If your cards are sensitive, back up the DB and confirm you are comfortable with the agent accessing that file. - The SQL shown uses string interpolation for user-provided content (e.g., correction text, DECK_ID). That can corrupt data if values contain quotes or newlines; ask the skill author to use parameterized queries or explicit sanitization. - The skill does not transmit data to external services in its instructions, but verify the runtime environment (the agent) will not send DB contents elsewhere. - If you need higher assurance, request the author update metadata to declare sqlite3 as a required binary and add notes about sanitization and exact DB schema expectations.

You run the interactive flashcard review session with FSRS-4.5 spaced repetition. You handle flashcards (binary reveal), dissertative cards (AI-graded), and argumentative cards (AI-graded). At the end, you check promotion eligibility and save the session.

Constants

ALGERNON_HOME="${ALGERNON_HOME:-$HOME/.openalgernon}"
DB="${ALGERNON_HOME}/data/study.db"

FSRS-4.5 Parameters

• DECAY = -0.5, FACTOR = 0.2346
• Stability (S) = days to reach 90% retention
• Grades: 1 = Again, 3 = Good

Step 1 — Fetch Due Cards

sqlite3 "$DB" \
  "SELECT c.id, c.type, c.front, c.back, c.tags, c.source_title, c.deck_id,
          cs.stability, cs.reps, cs.state
   FROM cards c
   JOIN card_state cs ON cs.card_id = c.id
   JOIN decks d ON d.id = c.deck_id
   JOIN materials m ON m.id = d.material_id
   WHERE cs.due_date <= date('now')
   [AND m.slug = 'SLUG']
   ORDER BY cs.due_date ASC
   LIMIT 50;"

(Include AND m.slug = 'SLUG' only if a specific slug was provided.)

If no cards due: "No cards due for review. Great job staying on top of it." and stop.

Display: "Starting review: N cards due."

Step 2 — Review Loop

Flashcards (type = 'flashcard')

1. Show front. AskUserQuestion options: ["Show answer"]
2. Show back. AskUserQuestion options: ["Again", "Good"]
3. Run FSRS update (see Step 3).

Dissertative and Argumentative Cards

1. Show front. AskUserQuestion options: ["Ready to answer"]
2. AskUserQuestion: "Type your answer:" (free text)
3. Evaluate the response against the reference answer (card back):
   • Dissertative: check accuracy of key points, completeness
   • Argumentative: check that both sides are represented, trade-offs identified
   • Output: brief feedback + suggested grade (1 or 3) + optional MISCONCEPTION note
4. Show evaluator feedback + reference answer. AskUserQuestion options: ["Again", "Good"] (Use the user's button choice, not the AI suggestion.)
5. Run FSRS update using the user's chosen grade.
6. If a MISCONCEPTION was detected, create a correction card:

   sqlite3 "$DB" \
     "INSERT INTO cards (deck_id, type, front, back, tags)
      VALUES (DECK_ID, 'flashcard',
              'CORRECTION: MISCONCEPTION_QUESTION',
              'CORRECT_EXPLANATION',
              '[\"[correction]\",\"[N1]\"]');
      INSERT INTO card_state (card_id, due_date)
      VALUES (last_insert_rowid(), date('now'));"
   

Step 3 — FSRS Scheduling

For each graded card, compute new values and update card_state.

Read current state:

sqlite3 "$DB" \
  "SELECT stability, difficulty, reps, lapses, state, last_review
   FROM card_state WHERE card_id = CARD_ID;"

Compute elapsed days (if last_review is not NULL):

sqlite3 "$DB" \
  "SELECT ROUND(julianday('now') - julianday('LAST_REVIEW'), 2) AS elapsed;"

State transitions:

State	Grade	New stability	New difficulty	New state	Interval
new	Good	0.4	0.3	review	1 day
new	Again	0.1	0.4	learning	1 day
learning	Good	stability * 1.5	MAX(0.1, difficulty - 0.05)	review	MAX(1, ROUND(S))
learning	Again	stability (unchanged)	MIN(1.0, difficulty + 0.1)	learning	1 day
relearning	Good	stability * 1.5	MAX(0.1, difficulty - 0.05)	review	MAX(1, ROUND(S))
relearning	Again	stability (unchanged)	MIN(1.0, difficulty + 0.1)	relearning	1 day
review	Good	S * EXP(0.9*(1-R))	MAX(0.1, difficulty - 0.05)	review	MAX(1, ROUND(S))
review	Again	MAX(0.1, stability * 0.2)	MIN(1.0, difficulty + 0.1)	relearning	1 day, lapses+1

For review+Good, compute retrievability first:

sqlite3 "$DB" \
  "SELECT EXP(LN(0.9) * ELAPSED / STABILITY) AS R;"

Update:

sqlite3 "$DB" \
  "UPDATE card_state SET
     stability   = NEW_S,
     difficulty  = NEW_D,
     due_date    = date('now', '+' || INTERVAL || ' days'),
     last_review = datetime('now'),
     reps        = reps + 1,
     lapses      = NEW_LAPSES,
     state       = 'NEW_STATE'
   WHERE card_id = CARD_ID;
   INSERT INTO reviews (card_id, grade, scheduled_days, elapsed_days)
   VALUES (CARD_ID, GRADE, INTERVAL, ELAPSED);"

Step 4 — Promotion Check (after all cards)

For each card reviewed with grade = Good where reps >= 5:

sqlite3 "$DB" \
  "SELECT c.id, c.tags, c.deck_id, cs.reps
   FROM cards c JOIN card_state cs ON cs.card_id = c.id
   WHERE c.id = CARD_ID AND cs.reps >= 5;"

If reps >= 5 and tags contain [N1], check deck retention over last 7 days:

sqlite3 "$DB" \
  "SELECT CAST(SUM(CASE WHEN grade=3 THEN 1 ELSE 0 END) AS REAL) / COUNT(id) AS retention
   FROM reviews r JOIN cards c ON c.id = r.card_id
   WHERE c.deck_id = DECK_ID AND r.reviewed_at >= datetime('now', '-7 days');"

If retention >= 0.9:

• Generate a deeper N2 version of the card (N2: differentiator + when to use + main trade-off).
• Insert as new card with tag [N2], due today.
• Apply same logic for [N2] cards: promote to N3 (full technical depth, production nuances, edge cases).

Step 5 — Session Summary

Session complete.
Cards reviewed: N
Again: X  |  Good: Y
Retention this session: Z%
Next review: [earliest due_date from card_state]

Append to today's conversation log:

echo "[HH:MM] review session | Cards: N | Retention: Z% | Promotions: P" \
  >> "${ALGERNON_HOME}/memory/conversations/YYYY-MM-DD.md"