Repair costly flashcards through approved edits

Implementation guide · untested

Source-supported actions are attributed evidence. Proposed steps, prompts, synthetic examples and checks are original editorial guidance; the workflow has not been run.

Why this agent / simpler alternative

Agent contribution

An agent can compare the wording of difficult cards, notice confusable cues, and prepare traceable revisions while keeping the learning target stable. Its value is a reasoned change proposal rather than declaring which facts deserve study.

Simpler alternative

Use Anki's browser and manually edit a few known troublesome notes when the learner already knows the issue. A simple lapse filter may be enough to choose a review queue.

Unsuitable when

The owner cannot identify authoritative answers, an import pipeline is undocumented, the collection cannot be safely backed up, or the intended request is to optimize scheduling parameters.

Source-supported scope

The recipe covers read-only diagnosis, small exact-change proposals and verification after approval. It preserves scheduling and distinguishes Anki-owned notes from externally maintained sources.

Setup — required, optional and unknown

Required

1. A learner-approved collection/deck scope and an isolated trial profile or disposable copy for the first mutation test.

2. A verified restorable backup and a record of where each candidate note is authored.

3. A current-content snapshot and a reviewer who can confirm the intended recall target and factual answer.

4. The source route uses Anki Desktop, AnkiConnect and Python's standard library.

Optional

1. Approved source excerpts for disputed facts and an existing personal card-writing style guide.

2. A short explicit exclusion list for private or high-stakes deck contents.

Unknown

1. The installed Anki, AnkiConnect and host-agent version combination is untested.

2. Behavior of the owner's importers, custom note types, media and external-source pipeline must be checked.

3. The diagnostic ranking is not a validated measure of learning gains.

Inputs and access

1. Name

   Scoped card and review data

   Format

   Anki records or a redacted export with card ID, note ID, fields, deck, tags, siblings and review signals

   Source or owner

   Collection owner

   Access scope

   Only the named deck/query; full raw fields for proposed changes

   Permission needed

   Authorize read scope and processing destination, especially for sensitive study material.

2. Name

   Conventions and source routes

   Format

   Owner-confirmed text: flag meanings, field use, source-of-truth route and preferred card style

   Source or owner

   Learner or deck maintainer

   Access scope

   This collection

   Permission needed

   Saving or changing convention files requires separate approval.

3. Name

   Target evidence

   Format

   Approved source excerpt or reference mapped to a note ID

   Source or owner

   Learner or educator

   Access scope

   Only facts needed to preserve the selected target

   Permission needed

   Confirm access rights and whether material can be sent to a model service.

4. Name

   Exact change decision

   Format

   Batch record: note IDs, old values, new values, affected siblings, decision and timestamp

   Source or owner

   Collection owner

   Access scope

   Displayed batch only

   Permission needed

   Explicit approval for the exact operation; deletion and sync are separate.

Documented source actions

1. 1

   Check connection, conventions and collection scope.

   Input: Local Anki Desktop; AnkiConnect at 127.0.0.1:8765

   Output: Read-only diagnosis

   Checkpoint: Stop if unavailable.

   Source: Route the request ↗

2. 2

   Show 1–4 exact proposals and destination.

   Input: Current note and siblings

   Output: Review batch

   Checkpoint: Explicit approval before writes; scheduling excluded.

   Source: Approval workflow for every mutation ↗

3. 3

   Apply at the source of truth; reread each item.

   Input: Approved batch

   Output: Change verification

   Checkpoint: Deletion and sync require separate confirmation.

   Source: Approval workflow for every mutation ↗

Proposed implementation steps — unexecuted

1. 1

   Prepare a repair brief containing the named deck/query, excluded material, backup location and known import route. List any ambiguous flag or tag meaning as a question. Keep the first trial separate from the learner's active collection.

   Input: Collection scope, backup and owner conventions

   Output: Repair scope and restoration checklist

   Checkpoint: The owner can identify the collection to restore and the content allowed for inspection; unknown flags are not interpreted as commands.

2. 2

   Build a candidate ledger with stable IDs, review counts, lapse counts, interval and the diagnostic used. Include a few lower-ranked comparison cards. Read the content before describing a problem, distinguishing a genuinely hard concept from an ambiguous cue or bundled response.

   Input: Scoped read-only review data

   Output: Candidate ledger and construction hypotheses

   Checkpoint: A high diagnostic score is a selection aid, not proof of bad wording or a reason to delete the note.

3. 3

   Retrieve complete raw fields, referenced media and every sibling for each selected note. Record the learner's intended answer and the authoritative editing location. Produce an impact map showing which card fronts, backs or source files would change; keep truncated previews out of write payloads.

   Input: Selected candidate IDs and source evidence

   Output: Full before-state snapshot and note-to-sibling impact map

   Checkpoint: A missing sibling, source route or unverified factual change blocks that item, not unrelated read-only work.

4. 4

   Draft a small review sheet. For each proposal, show exact old/new fields, the specific cue defect, the preserved target and any open factual question. Prefer one change per note for the pilot so the reviewer can see what caused a difference. Include a skip option.

   Input: Impact map and learner target

   Output: Exact-change proposal with item-level decisions pending

   Checkpoint: The proposed answer still tests the approved target; broad deck cleanup is not smuggled into a wording repair.

5. 5

   For a later authorized trial, reread the current note immediately before writing and compare it with the snapshot. Apply only approved unchanged items to their authorized source. Record each individual result; if one write fails, leave it failed rather than reporting the batch as complete.

   Input: Approved item-level decisions and before-state snapshot

   Output: Per-item application ledger with applied, skipped, conflicted or failed states

   Checkpoint: A concurrent edit or changed import source invalidates the old preview and sends that item back for review.

6. 6

   Reread changed content and inspect the affected cards in the disposable profile. Compare schedule/history snapshots, check formatting and media, and record any side effect. Deliver a concise result and restoration instructions; propose a later learner review rather than claiming improved retention.

   Input: Application ledger and approved field values

   Output: Verification report and unresolved-item queue

   Checkpoint: Exact approved values and protected-state preservation are required. The learner decides separately about syncing or changing targets.

Original starter prompt — proposed

Origin

editorial_proposal

Text

Inspect {deck_or_query} under {confirmed_conventions} using only {authorized_read_scope}. Identify a small set of cards whose wording may increase review friction; explain the evidence without claiming to detect missing knowledge. For candidates, retrieve complete fields and siblings, identify {source_of_truth}, and show exact before/after proposals that preserve the learner's target. Ask about uncertain facts. Stop before every mutation until the displayed item is explicitly approved. Do not change scheduling, delete, sync, tag or save convention files as a side effect. Return a per-item verification plan and backup requirements.

Placeholders

1. deck_or_query

2. confirmed_conventions

3. authorized_read_scope

4. source_of_truth

Limitations

Original draft-first prompt. A later approved edit still requires a safe environment, fresh before-state and the owner's exact decision.

Synthetic worked example — not an agent run

Status

synthetic

Label

Invented repair proposal; no real collection was inspected or edited

Content

Note id

demo-note-12

Card ids

1. demo-card-12a

2. demo-card-12b

Source route

Anki-native, fictional

Preserved target

Expansion of the abbreviation CPU

Before

Front

CPU?

Back

Central processing unit

Proposed after

Front

What does the abbreviation CPU stand for?

Back

Central processing unit

Reason

Make the requested type of response explicit.

Affected siblings

Both fictional cards generated from this note need preview.

Factual status

Answer supplied by fixture author, not newly verified here

Approval

pending

Applied

No

Artifact url

Not specified.

Costs and effort — unmeasured

Verified prices

Setup work

1. Establish the backup/restore path, scope, note ownership and conventions.

2. Prepare a trial collection and inspect the proposed integration before authorizing it.

Recurring work

1. Review individual before/after changes, verify factual targets and resolve import/concurrency conflicts.

2. Inspect affected sibling cards and judge whether the revised cue works during normal later study.

Unknowns

1. Model costs, read latency, review burden and retention effects have not been measured.

2. No evidence establishes that repair is faster than manually editing a small known queue.

Failure modes

1. Signal

   A proposal changes what must be recalled rather than clarifying the cue.

   Consequence

   The learner loses control of the learning target.

2. Signal

   One field edit unexpectedly changes several sibling cards.

   Consequence

   A repair fixes one card while breaking others.

3. Signal

   The next import overwrites the change.

   Consequence

   The wrong source of truth was edited.

4. Signal

   Current fields differ from the approved preview or only some batch results succeed.

   Consequence

   Approval no longer matches the action or success is overstated.

Recovery steps

1. Trigger

   A before-state conflict appears.

   Action

   Skip that item, show the newer content and produce a new proposal. Do not overwrite another editor's work with a stale approved payload.

   Stop condition

   No fresh item approval is available.

2. Trigger

   Sibling formatting, media or protected-state comparison fails.

   Action

   Stop remaining mutations, preserve the ledger and seek approval for a targeted restoration using the captured original content or verified backup.

   Stop condition

   The original state cannot be established safely.

3. Trigger

   The source route is wrong or an import reverses the edit.

   Action

   Identify the authoritative source and importer behavior, then prepare a new exact proposal at that destination.

   Stop condition

   Do not repeatedly patch the generated note or attempt an unapproved import/sync.

Source-observed and proposed approval boundaries

Source observed

Exact mutations need approval; deletion and sync have distinct confirmation gates.

Editorial recommendations

1. Scope any export or model processing to owner-approved deck content.

2. Backups, writes and later restorations are explicit operations, not implicit approval to alter the collection.

3. No suspended/deleted/retargeted notes or new tags as cleanup side effects.

4. Retain the initial trial in a disposable profile; do not promote it to a live collection without approval.

Unexecuted validation plan

Fixture

Unexecuted proposal: a disposable collection of six fictional notes, including an ambiguous abbreviation cue, a two-card sibling note, an externally authored note, a note with media, a concurrently changed field and one difficult but well-written control.

Acceptance checks

1. The difficult control can remain unchanged despite its diagnostic rank.

2. The exact preview shows every affected sibling and routes the external note to its source.

3. A stale before-state is skipped, and partial batch failure remains visible.

4. Applied values match the approved preview exactly; scheduling and review history are unchanged.

5. No deletion, sync, tagging or convention persistence occurs without its own approval.

Stop conditions

1. No verified restoration path.

2. Unclear source-of-truth ownership or unverified target facts.

3. Any protected-state change, missing sibling or unapproved mutation.

4. A partial failure is incorrectly reported as complete.

Executed

No

Limits

1. No Anki instance was connected, no collection was read and no changes were applied.

2. This is a community recipe, not evidence of improved retention or reduced study time.

3. Source publication date and tested host-version matrix remain unknown.

4. Sensitive or professional study content needs appropriate owner review; the guide does not validate its facts.

Guide source links

https://github.com/djt97/anki-skill/blob/main/anki/SKILL.md ↗
documented_steps; approval_boundaries.source_observed

https://github.com/djt97/anki-skill/blob/main/anki/references/health-check.md ↗
Proposed diagnosis boundaries; see referenced source section.