jotbook-pencil-review
Skill0 starsChanged 5 months agoMITView on GitHub
Review the pencil backlog and decide which provisional drafts to ink, drop, revise, edit, or keep.
In this repository8 other files it gives its agents.
- jotbook-initSkill
- jotbook-inkSkill
- jotbook-linkSkill
- jotbook-pencilSkill
- jotbook-reviewSkill
- jotbook-stageSkill
- jotbook-templateSkill
- jotSkill
The file
We split this skill into the rules it gives an agent
12 rules. About 0 are common, 4 are distinctive, and 8 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈4
Distinctive · estimate
This author's own choices. Worth a look.
8
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 12
Read .claude/jotbook.local.md if present.
- Very specific: line 19
If pencils_dir doesn't exist or contains no pencils, report that in one line and stop.
- Very specific: line 27
Read the metadata block — YAML frontmatter for .md pencils, the top HTML comment for .html pencils.
- Very specific: line 33
Check that each entry in from_jots: still resolves to a real file in jots_dir.
- Distinctive: line 69
Ask the user in plain language.
- Distinctive: line 83
Default to keeping source jots.
- Distinctive: line 91
After applying, give a one-line summary:
- Distinctive: line 101
Don't promote, drop, or regenerate without explicit confirmation.
- Very specific: line 102
Don't read source files referenced by sources: during review — the pencil body is enough to evaluate.
- Very specific: line 103
Don't propose drafting new pencils — that's /jot pencil <slug>.
- Very specific: line 104
Don't proceed if pencils_dir is empty — report and stop.
- Very specific: line 105
Don't silently invoke jotbook-ink or jotbook-pencil for an action the user hasn't explicitly marked.
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Review the pencil backlog
The user is reviewing the pencils (provisional long-form drafts) to decide which are worth promoting to inked entries, which need a revise pass, and which should be dropped. Your job is to surface and recommend — never delete, promote, or regenerate unilaterally. Every action needs explicit confirmation.
Resolve configuration
Read .claude/jotbook.local.md if present. From its frontmatter, extract:
| field | default | meaning |
pencils_dir | docs/jotbook/_pencils/ | where pencils live |
jots_dir | docs/jotbook/_jots/ | needed to verify source-jot existence |
If pencils_dir doesn't exist or contains no pencils, report that in one line and stop.
Procedure
1. Inventory
List every *.md and *.html file under pencils_dir (excluding any README.md). For each:
- Read the metadata block — YAML frontmatter for
.mdpencils, the top HTML comment for.htmlpencils. Extract:status(should bepencil— flag anything else as suspicious)drafted:daterevised:date (if present)from_jots:list
- Compute age as today − (most recent of
revised,drafted). - Check that each entry in
from_jots:still resolves to a real file injots_dir. Note any missing source jots — the pencil can still be promoted, but its source-jot cleanup will be partial. - Record the format (
mdorhtml).
Sort by age, oldest first.
2. Present
Output a compact, scannable summary. Don't over-format — the user is making decisions from this view.
Suggested shape:
Pencils (N total):
▸ 2026-05-12 cache-eviction-policy (10d) md
From jots: 2026-05-02-cache-eviction-policy
▸ 2026-05-15 feature-flag-system (7d) html
From jots: 2026-05-04-flag-rollout, 2026-05-05-flag-telemetry
Revised: 2026-05-18
▸ 2026-05-18 webhook-retry-semantics (4d) md
From jots: 2026-05-10-webhook-retry-semantics [MISSING]
Recommendations:
• cache-eviction-policy: ready to ink — concrete, sources still present,
no revise history.
• feature-flag-system: ink or keep — recent revise suggests it's settled.
• webhook-retry-semantics: source jot is gone; still promotable but
flag this to the user before inking.Lead with the inventory; put your recommendations at the end. Keep the whole thing scannable — short lines, no walls of prose.
3. Solicit decisions
Ask the user in plain language. Don't present a numbered menu — let them respond free-form. Mention all five available actions so the surface is visible:
Decisions? You can say things like "ink cache-eviction-policy", "drop feature-flag-system", "revise feature-flag-system — focus on rollout only", "edit webhook-retry-semantics" (no regen, just give me the path), or "keep everything for now".
4. Apply
For each decided action:
- Ink
<slug>— hand off tojotbook-inkwith the slug. The ink skill detects the pencil's existence and runs its Promotion path (skipping gather/plan/render, swapping pencil frontmatter for entry-appropriate frontmatter peroutput_format, writing toentries_dir, updating cross-links into related entries, deleting the pencil + source jot(s)). Confirm with the user before running if you noticed missing source jots in the inventory. Drop
<slug>— delete the pencil file. Before deleting, ask one question:"Drop pencil
<slug>. Source jot(s) (<list>) can stay (default) so you can redraft later, or be deleted alongside the pencil. Which?"Default to keeping source jots. If the user explicitly says delete-all, also remove the source jots.
- Revise
<slug>—<notes>— invokejotbook-pencilwith the slug and pass the user's notes to its revise sub-procedure. The pencil skill applies the notes to the existing pencil in place and bumpsrevised:to today. If the user saidrevisewithout notes, ask once for the notes before proceeding. - Edit
<slug>— no-op. Surface the file path so the user can hand-edit it. Mention they can re-run/jot review pencilsonce they're done. - Keep — no-op for now.
After applying, give a one-line summary:
Inked N, dropped M, revised R, edited E, kept K. Source jots deleted: <list>.Omit the "Source jots deleted" tail if no source jots were deleted.
What NOT to do
- Don't promote, drop, or regenerate without explicit confirmation.
- Don't read source files referenced by
sources:during review — the pencil body is enough to evaluate. Save deep reading for the user (or for ink time). - Don't propose drafting new pencils — that's
/jot pencil <slug>. This skill only acts on existing pencils. - Don't proceed if
pencils_diris empty — report and stop. - Don't silently invoke
jotbook-inkorjotbook-pencilfor an action the user hasn't explicitly marked.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

