Writing Flashcards

Hard Output Contract (Non-Negotiable)

Applies whenever you produce cards (stdout or writing into a file).

Exception: if you are refusing/stopping because required inputs are missing, do not output cards. Output a short request for the missing stable URL/permalink and (if deduping/merging is required) the vault path.

When producing cards, your response/output file must contain only flashcards + footnote definitions at the very bottom.

Per card:

• Line 1: **<question>** #card <optional tags>
  • #card is mandatory on every card.
• Line 2+: <answer> (Markdown allowed)
• Final line of the card: footnote markers only, on their own line: [^slug1][^slug2]
  • Nothing may appear after this line (no IDs, separators, extra whitespace blocks).

Global rules:

• No headings, numbering, TOCs, metadata blocks, prose, or file-system commentary in the output.
• Never preface with “available skills / skill match / I will…”; the output must be cards-only.
• Never include tool/harness artifacts like <task_metadata>...</task_metadata>.
• Separate cards with a single blank line.
• Never put URLs in answer text (citations are footnotes only).
• Exactly one footnote-marker line per card (no markers sprinkled in the answer).
• Footnote definitions are collected at the bottom only:
  • [^<slug>]: [<Title>](<URL>)

Tag + Linking Rules

• #card is mandatory on every card.
• Add other tags only if the user requested them (difficulty, exam code, topic tags).
• Difficulty calibration (only if requested):
  • #beginner: definitions, defaults, primary purpose.
  • #advanced: trade-offs, decision rules, key operational limits.
  • #expert: edge cases, internals, precise failure modes/scenarios.
• Never use wiki links in questions.
• Answers may include wiki links for likely-in-vault concepts (e.g., [[Amazon S3]]); otherwise leave unlinked.

Question/Answer Quality

• Atomic and specific: one recall target per card.
• Source-checkable: every answer must be supported by the cited section.
• No marketing language; paraphrase in plain English.
• Forbidden question openings: Is, Does, Can, Are.
  • Reframe as: “What is…”, “How does…”, “What is the behavior of…”, “What is the difference between…”.
• Avoid “Tell me about …”.

Question Style by Difficulty:

Citations, Deep Links, and Slugs

Source rules

• Use only user-provided URL(s). Do not add “helpful” extra sources.

Deep-linking rules

• If the page supports anchors, cite a deep link to the most relevant section.
• Never guess an anchor. Verify it exists in fetched content (the HTML contains id="anchor", name="anchor", or a link href="#anchor"). If you can’t fetch/verify, do not use an anchor.
• Fallback if no verifiable anchors: cite the closest stable section URL available (often the page URL without an anchor).

Slug rules (derived from source section, not card content)

• Slug identifies the cited source section: (<url filename> + <anchor>).
• All cards citing the same section must reuse the exact same slug.
• Slug format:
  • lowercase
  • - separator
  • strip query strings
  • examples:
    • .../storage-class-intro.html#sc-compare → storage-class-intro-sc-compare
    • .../optimizing-storage-costs.html → optimizing-storage-costs

Zero-Duplicate + Minimal-Churn Update Policy

Treat the vault as the source of truth for whether a card should exist.

For each candidate fact:

• skip: an equivalent card already exists and is accurate.
• update: only if the card is demonstrably wrong/outdated per the cited section.
  • Make the smallest edit that restores correctness.
  • Preserve unrelated wording and tags as long as the Hard Output Contract still holds.
  • Do not add vault-specific trailing markers (e.g., Obsidian block IDs like ^...) unless the user explicitly asked for them.
• create: only if missing.

If a new source adds authoritative confirmation/context to an existing accurate card:

• Add additional footnote markers to that card’s marker line (still one marker line).

If multiple provided sources overlap:

• Extract the fact once.
• Cite the most authoritative section; add multiple footnotes only if they add distinct value.

Placement Policy (When Writing Into Existing Files)

• If the target file has bottom-of-file footnote definitions ([^slug]: ...), insert new/updated cards above the first footnote definition.
• If the file has topic headers, insert under the most relevant header but still above bottom-of-file footnotes.

Workflow (Use This Every Time)

1. Validate inputs: stable URL(s) present; user allows only those sources.
2. Fetch sources: extract candidate facts (definitions, contrasts, limits, if/then behaviors, enumerations); collect verifiable anchors.
3. Right-size: produce only as many cards as the source warrants; never pad.
4. Vault dedupe: search the vault for each candidate (by topic + synonyms, not just exact wording).
5. For each candidate: decide skip / update / create.
6. Assemble output: cards first, then footnote definitions; enforce the Hard Output Contract.
7. Final validation checklist (must pass before emitting):
   • No non-card text; no headings; no numbering.
   • No URLs in answers.
   • Every card ends with exactly one footnote-marker line.
   • Every footnote marker has exactly one definition at bottom.
   • Slugs are section-derived and reused consistently.
   • No duplicate cards.

Common Failure Modes (Red Flags → STOP)

• Adding “helpful” explanation outside cards (violates card-only output).
• Using placeholder markers like [^1] (violates slug policy).
• Adding anything after the footnote-marker line (violates per-card structure).
• Guessing anchors because “it’s probably right” (violates deep-link verification).
• Creating a new card for an already-covered fact (violates zero-duplicate).
• Multi-fact dumping (one card trying to cover an entire comparison table).