Reading Notes

Turn supplied resources into useful review notes and a concrete homework list.

Decision Tree

What did the user provide?

• Raw notes, pasted bullets, or a live note dump

Treat the text as source material. Preserve the user's rough structure, repair obvious grouping, and extract homework without pretending the notes are complete.

• A local document, PDF, slide deck, spreadsheet, image, audio file, or video file

Read references/intake.md, extract the available text and visual/audio signals, then continue with the default workflow.

• A webpage, article, RFC, issue, pull request, or public URL

Read references/intake.md. Capture the title, URL, date if visible, and access limitations before summarizing.

• A YouTube or other video URL

Read references/intake.md. Prefer a transcript or captions first, then supplement with visible metadata. If no transcript is available, say that and ask for one only after producing whatever can be grounded.

• The user asks for "homework", "stuff to research", "what should I do next", or "turn this into todos"

Read references/synthesis.md and make the action list explicit.

• The user asks to save, export, share, or convert the notes

Read references/output-formats.md. Produce the notes first, then ask which format to save unless the user already specified one.

Quick Reference

Default Workflow

1. Identify the resource type and access path. If no resource is present, ask for the notes, link, file, transcript, or screenshot.
2. Capture source metadata: title, author/speaker if known, event/context, URL/path, date, and access limitations.
3. Extract content with the least lossy available method. For long resources, chunk by section, timestamp, heading, slide, or topic.
4. Build a topic map before writing final notes. Group by subject, not by the order in which fragments appeared.
5. Pull out interesting ideas: surprising claims, useful techniques, tradeoffs, open debates, references, named tools, and concepts worth revisiting.
6. Convert worthwhile follow-up into homework todos with concrete verbs: read, verify, compare, prototype, ask, install, benchmark, write, create, or decide.
7. Separate fact, inference, and question. Mark uncertain items instead of smoothing them into confident statements.
8. Return the notes in Markdown unless the user requested another format.
9. End by asking whether to save or export the notes, naming practical options such as Markdown, DOCX, PDF, or a task-list format.

Output Contract

Use this shape by default. Omit empty sections, but keep the todo and research sections when the user wants homework.

# <Resource or Session Title>

## Snapshot
- Context:
- Source:
- Confidence:

## Topics
- <topic>: <one-line explanation>

## Interesting Ideas
- <idea>: why it matters or why it is worth revisiting

## Homework / Todos
- [ ] <verb-first action>

## Further Research
- <term, tool, paper, RFC, person, library, or question to look up>

## Open Questions
- <uncertainty, missing source, or question to ask later>

Quality Bar

• Keep bullets high signal. Do not rewrite the whole source as a compressed transcript.
• Make todos actionable enough that the user can start work later without rereading everything.
• Preserve named references, commands, URLs, libraries, products, people, and RFCs.
• If source access is partial, say exactly what was available and what was missing.
• Use citations or source anchors when available: URLs, page numbers, timestamps, headings, slide numbers, or file paths.

Reading Guide

Gotchas

1. A transcript is not the whole talk. Demos, slides, diagrams, code, and audience questions can carry important context.
2. Messy live notes are evidence, not a complete source. Keep uncertainty visible.
3. A vague todo like "research ClickHouse" is weak. Prefer "Compare ClickHouse MergeTree primary key design against common Nightwatch dashboard queries."
4. Interesting does not mean merely mentioned. Promote items that are surprising, useful, controversial, reusable, or connected to later action.
5. Do not ask about export format before producing the notes unless the user's main request is file creation.

Verification Notes

The helper script is deterministic and only classifies source descriptors. It does not fetch content or summarize. Verify command syntax with --help and package behavior with scripts/test_skill.py.