notes-v3.6 — Revision Notes Generator: Verified Coverage & Source Transparency

notes-v3.6 — Revision Notes Generator: Verified Coverage & Source Transparency

Complete rewrite of the revision-notes-generator skill, driven by a systematic diff of generated outputs against their sources (PMT Mechanics & Materials, SME Newton's Laws, SME Classification of Particles). The previous version produced accurate notes but with three hidden failure modes: coverage varied between runs, knowledge was added from outside the source without any marker, and the accuracy-verification instruction produced no observable behaviour. This release makes all three visible and testable.

What's New

Coverage map and mandatory verification

The skill now builds an explicit checklist of every subheading, method, equation, and condition in the source before writing, and runs a mandatory verification pass against it before output. This closes the run-to-run drift where method steps (e.g. resolving projectile velocity components, the maximum-height condition) appeared in one run and vanished in the next.

Flagged beyond-source additions

Adding correct knowledge beyond the source is permitted when needed for complete understanding, but every addition must now be marked inline:

(Beyond source: the added fact.)

Previously, silent additions could contradict nearby source content. In testing, an unmarked insertion produced notes stating both "strong force → gluon" and "pion is the exchange particle of the strong force" with no reconciliation.

Error flagging instead of silent correction

Source statements that conflict with standard A-Level treatment are kept and flagged:

⚠ Check: source states X; standard treatment is Y.

The old "correct any errors" instruction never visibly fired and risked invisible rewrites. In validation, the new behaviour caught a genuine error in a PMT source (a duplicated specification section number) on its first run.

Worked example policy

Worked examples that teach reusable methods (conservation-law checks, SUVAT strategy, quark deduction, equilibrium proofs) are compressed and retained inline. Pure number-substitution examples are dropped. Previously this was unspecified, so examples survived or vanished at random.

Signal density replaces length-based conciseness

Conciseness is now defined as every sentence defining, explaining, or connecting a concept, with no length cap. Long, dense sources produce long, dense notes.

Self-contained output

Diagram content must be translated into prose or tables. "See source" references are banned. In validation, Feynman-diagram-only content (kaon production via gluon, decay via W boson) was correctly extracted into text.

Conditional tier labelling

(HT) marking now applies only to GCSE sources. A-Level sources have no tiers, so the previous always-on instruction was dead weight.

Output Changes

Notes generated by the updated skill differ visibly from previous releases:

• *(Beyond source: ...)* and ⚠ Check: markers may appear in the body
• Source section numbering is retained in headings for spec cross-referencing
• Equations are rendered in LaTeX rather than code blocks
• Compact inline worked examples appear throughout
• Outputs are typically ~40% longer due to retained methods and examples

If you post-process these notes (e.g. into flashcards), account for the new marker syntax.

Validation

Tested on two source families with output-vs-source diffs:

• PMT Mechanics & Materials: previous coverage gaps closed, one genuine source error caught and flagged, two legitimate beyond-source additions correctly marked
• SME Classification of Particles: all five method-teaching worked examples retained, Feynman diagram content translated, one false-positive flag traced to a source-specific example embedded in the skill (fixed by replacing it with a generic placeholder)

Known Limitations

• Source-internal contradictions (the source disagreeing with itself across sections) can occasionally pass the verification pass
• The worked-example filter occasionally retains a trivial number-substitution example
• Flagging thresholds are conservative: muddled-but-defensible source phrasing may go unflagged

Skill-Writing Lesson

Never embed real content from the target source corpus as an illustrative example inside a skill. During validation, the model pattern-matched an embedded gluon/pion example and mis-flagged that exact content as beyond-source when it actually appeared in the source's tip box. Examples in skills should always be generic placeholders.

flashcard-v3.6 - Improved anki-flashcard-generator skill

anki-flashcard-generator v3.6

Major rebuild of the skill around a single design principle: rules block defects, examples convey style. Testing across model versions showed that prescriptive style rules (rigid atomicity targets, mandatory "why/how" framing, universal bidirectional cards) globally distorted deck character, while defect-blocking rules cost nothing. v3.6 restores the terse, exam-aligned register of the original prompt versions while keeping the two genuine gains of v3.3–v3.5: accuracy verification and targeted interference management. The skill is roughly one third the length of v3.5.

Changed

• Atomicity softened to "one idea per card, judged flexibly" — a definition may bundle one directly associated detail (its formula, unit, or key property) when naturally recalled together. Never a reasoning chain or second independent concept
• New bundle-or-split rule — a detail bundled into a definition must not also get its own card, and no answer may contain another card's answer. Closes the pay-twice duplication observed in earlier versions (e.g. "measured in Pa" inside a definition alongside a separate unit card)
• Reverse cards scoped to key terms only (terms the exam asks candidates to define), replacing the universal bidirectional rule that doubled deck size. Scoping self-adjusts by deck type: sparse on topic notes, near-complete on definition sheets
• Interference check constrained to exactly two cases — contradicting cards (rephrase to name context) and pairs the source itself contrasts (one compare card stating the point of divergence). Compare/contrast is no longer a free card type; duplicate compare cards are banned
• Verification step reworked — clear factual errors are fixed; possible syllabus-level simplifications are kept and flagged in the chat response, never silently rewritten and never written into the output file
• Explain cards demoted — only where the source itself explains the reasoning and it is a likely exam point, mechanism stated in at most two sentences. Recall content is never converted into explain cards
• Card-count anchor removed — deck size is determined by content density; the material decides

Added

• Pipe-character exclusion — | is banned inside questions and answers (write "magnitude of v", not |v|), preventing silent import corruption
• Circular-answer exclusion — answers that merely restate the question are omitted and flagged (a defect that survived four prompt/skill generations before being named)
• Brevity tiebreaker — when any style rule conflicts with brevity, brevity wins. Resolves the rule conflict that drove v3.5's answer padding
• Bad→good rephrase example on the yes/no ban — the one rule observed to slip under v3.5-era instructions now teaches by example
• Bundled-definition example (impulse: definition + Ft = Δp) and a non-physics example (binary search complexity) signalling domain generality

Removed

• Depth of processing, personal connection, dual coding, and understand-first principles, plus all retention-science rationale prose — identified as the primary drivers of register drift
• The 6-second answerability and 25-word answer targets
• The quality checklist (redundant with the rules)
• All GCSE-era "Higher Tier" references

Validation

Tested on AQA A-Level Physics sources (Classification of Particles topic notes; Mechanics & Materials definition sheet), run both inside and outside Claude projects:

• Outputs converged to near-identical decks across project/no-project conditions, demonstrating the skill dominates both model defaults and project memory
• Controlled comparison against a bare minimal prompt on the same model showed the skill suppresses model-default elaboration: unsolicited verification/worked cards, yes/no questions, and bundle-plus-duplicate redundancy all appeared without the skill and not with it
• Every defect class identified across v2–v3.5 decks (answer padding, answer leakage, deck doubling, duplicate compare cards, unit-leak duplication, circular answers) is fixed or reduced to single-line generation variance

Companion artifacts

• anki-flashcard-prompt-v5 — standalone fallback prompt with full instruction parity, for use when the skill feature is unavailable. Keep in sync with SKILL.md
• README updated to match v3.6, including the defect-blocking vs style-by-example design rationale and per-version notes

Upgrading

Drop-in replacement for the existing SKILL.md — same name, same trigger phrases ("Anki flashcard" / "Anki deck"), same output format. Decks generated under v3.3–v3.5 remain import-compatible; expect new decks to be terser, smaller, and free of the padding and duplication patterns above. If project memory contains card-design principles from earlier versions, remove them and defer to the skill as the single source of truth.

v3.5 — Leaner skill, same output

Trimmed ~39 lines of unnecessary rationale and redundancy from the Anki flashcard generator skill (236 → ~197 lines), without removing any functional instructions that affect card generation behaviour.

What changed

• Removed cognitive science rationale from Core Design Principles — Explanatory paragraphs about forgetting curves, meta-analytic effect sizes, neural encoding circuits, and picture superiority effects were removed. The actionable rules and heuristics they supported are unchanged.
• Removed Leech prevention subsection — Every bullet was already covered by existing rules (atomicity, unambiguous phrasing, compare/contrast cards, understand-first).
• Removed Cloze cards and Conciseness rationale paragraphs — Kept the usage guidance and rules; removed the research justifications.
• Trimmed Quality Checklist from 14 items to 5 — Removed 9 items that directly restated rules from card type sections or other parts of the skill. The 5 remaining items cover checks not already enforced elsewhere.
• Removed dual coding HTML comment — A disabled comment explaining why image tags were off; the active instruction already covered this.

What was deliberately kept

High-impact redundancies were retained where they reinforce critical rules: bidirectional definition cards, production over recognition, understand-first, diagram exclusion, and interference management.

Net result

Every remaining line directly influences card generation behaviour. Zero functional instructions lost.

v3.4 - Anki Flashcard Generator: Evidence-Based Card Design

Comprehensive update to the Anki Flashcard Generator skill with evidence-based card design principles grounded in cognitive psychology and neuroscience research.

What's New

• Core Design Principles — 6 principles ordered by impact on retention: understand-first rule, minimum information (atomicity), production over recognition, depth of processing, dual coding, and personal connection
• Card Types — 6 defined card types: definition (forward + reverse), explain/justify, cloze-style, compare/contrast, formula/equation, and enumeration
• Coverage Guidance — Content prioritisation by examinability, from high-priority definitions and equations down to supplementary context
• Quality Checklist — Comprehensive review checklist covering atomicity, production-based questioning, interference prevention, and output formatting

Improvements

• Expanded Card Design Rules — Now includes unambiguous phrasing, interference management, leech prevention strategies, and explicit exclusions
• Updated Process — Added accuracy verification (step 2) and interference checking (step 5) to the generation workflow
• Refined Output Format — Simplified format description; removed file naming from skill scope
• README Updated — Anki Flashcard Generator section synced with all SKILL.md enhancements

v3.3 - Cleaner Revision Notes

revision-notes-generator

New: Cleanliness criteria — Added explicit guidance to produce cleaner, less cluttered revision notes.

Changes

• Added "Clean" writing guideline — Notes now explicitly exclude specification codes, redundant headers, and formatting artefacts from source materials

• Added specification code exclusion rule — Syllabus reference codes (e.g., "1.1.3 a)", "1.1.3 b)") are now filtered out, keeping focus on actual knowledge content

• Updated quality checklist — New checklist item ensures specification reference codes are not included in final output

Why this matters

Educational source materials often contain specification codes that reference curriculum standards. While useful for teachers, these codes add noise to student revision notes. This update ensures generated notes focus purely on the knowledge content.

v3.2 - Accuracy Verification & Sample Prompts

What's New in v3.2

Anki Flashcard Generator Improvements

Accuracy verification step added: The flashcard generation process now includes an explicit step to verify accuracy of all source information and correct any errors before generating cards. This ensures higher quality flashcards with verified facts.

The process now follows 5 steps:

1. Read the source file thoroughly
2. Verify accuracy — correct any errors (new)
3. Identify key content (bolded terms, highlighted text, Higher Tier material)
4. Generate flashcards
5. Output as text file

Documentation Improvements

• Added sample prompts for all skills: Each active skill now includes a clear example prompt showing users exactly how to invoke the skill:

  • extracting-pdfs: Prompt terminology updated to "Sample prompt to use the skill"
  • anki-flashcard-generator: Added sample prompt section
  • revision-notes-generator: Added sample prompt section

• Consistent terminology: Unified section headings across all skill documentation for better clarity

---

Full Changelog: 5861909...6d9e43c

v3.1 - Anki Flashcard Generator Updates

What's Changed

Anki Flashcard Generator Improvements

• Output file naming: Added specification for naming output files after source files (e.g., Physics_Chapter_5.pdf → Physics_Chapter_5.txt)
• Output format examples: Added comprehensive examples showing the Question | Answer format with real flashcard samples
• Improved documentation: Enhanced card design rules and quality checklist

Commits

• fde69b3 Update SKILL.md with output format example
• 609213d Specify output file naming format in SKILL.md

---

All skills in this repository share a unified version number.

v3.0 - Major Documentation Overhaul

What's New

Complete documentation overhaul with comprehensive coverage of all 5 Claude Agentic Skills.

Skills Documented

Skill	Purpose	Status
extracting-pdfs	Extract and clean PDF content to markdown	Active
anki-flashcard-generator	Generate Anki-importable flashcard decks	Active
revision-notes-generator	Create concise revision notes from study materials	Active
pdf-extract	PDF extraction (development version)	Development
pdf-to-markdown-converter	Legacy PDF conversion	Deprecated

Changes

• Added skills overview table with status indicators
• Documented extracting-pdfs as the active production version
• Added anki-flashcard-generator documentation with triggers and output format
• Added revision-notes-generator documentation with writing guidelines
• Clarified pdf-extract as development version
• Updated project structure to reflect all skill directories
• Added unified versioning section

Dependencies

pip install pymupdf pymupdf4llm

extracting-pdfs v2.0

Update from pdf-extract v1.4:

• Review with the Agentic Skill docs and followed the best practices
• Updated name
• Updated instructions

pdf-extract v1.4

Improve from v1.3, added more clear instruction about Claude manually handle the cleanup process.