| name | zettel-quality-rework |
| description | Qualitative rework of z-yap zettels classified as IMPL-MAP or MIXED. Reads zettels, assesses design content, proposes per-zettel actions, gets user feedback, then executes rewrites, removals, and new zettels. Use when the user asks to improve zettel quality, rework a cluster, or tackle items from the zettel quality backlog. |
| disable-model-invocation | true |
Zettel Quality Rework
A phased campaign for turning implementation-map and mixed-quality zettels into durable design knowledge — extracting rationale, creating atomic concept/decision zettels, and updating the graph.
Quality theory is canonical in the zettelkasten skill (z-yap/.cursor/skills/zettelkasten/SKILL.md § Quality theory): the future-reader test, what a zettel is / is not, prose economy and the negative-framing table, structural patterns, connection principles, and tag hygiene. Read that section before assessing — this skill does not restate it. What follows is the rework process plus the assessment-specific classification guide and lessons learned.
Backlog
The current backlog is at z-yap/tmp/zettel-quality-backlog.md. Read it to see completed clusters and remaining work grouped by domain.
Process
A strict 4-phase process. Do NOT skip phases or combine them.
Phase 1: Read and assess
- Read ALL zettels in the cluster.
- Read their connections in
z-yap/connections.md.
- Read adjacent/related zettels referenced in those connections — adjacent zettels are often in the same state.
- Check
z-yap/REGISTRY.md for relevant tags and labels.
For each zettel, identify:
- Current state — what it says now, what's stale, what's accurate.
- Buried design content — rationale, decisions, principles, tradeoffs hidden in a code walkthrough.
- Overlap — which zettels say the same thing from different angles.
Classify each zettel to decide its action:
| Category | Description | Action |
|---|
| DESIGN | Has a "why" claim, tradeoff, decision, principle | Keep or light rewrite |
| IMPL-MAP | Primarily src/ paths, dispatch traces, module inventories | Rewrite, fold, or remove |
| REFERENCE | External theory/paper bridge | Keep; strip impl-map if present |
| HUB | Structural work-layer node | Keep; verify links are current |
| EXPLORATION | Speculative/open design sketch | Keep; strip impl-map if present |
| MIXED | Some rationale buried in implementation surface | Highest-value rewrite targets |
Phase 2: Propose actions
Present each zettel to the user with:
- Current state — 2-3 sentence summary.
- Buried design content — what's worth extracting.
- Proposal — one of: rewrite, remove, fold, split, keep, light rewrite.
Also propose:
- New zettels — atomic ideas without a home yet (concepts, decisions, ADRs).
- Removals — pure status reports or near-duplicates.
- Renames — when a zettel's name no longer matches its content.
End with a summary table: | Zettel | Action | Atom |.
Phase 3: User feedback
Wait for per-zettel feedback. The user may accept, redirect (different framing/split/scope), expand scope (pull in adjacent zettels), or correct factual claims (verify externally if uncertain). Iterate until the user says to execute.
Phase 4: Execute
- Write/rewrite zettel files (apply the
zettelkasten skill's creation and rewrite procedure).
- Delete removed zettels.
- Update
z-yap/connections.md: remove edges referencing deleted zettels; redirect edges to replacements where semantics are preserved; add edges for new zettels; deduplicate; add new zettels to relevant thread INCLUDES.
- Register new tags/labels in
z-yap/REGISTRY.md if needed.
- Check for dangling references: grep deleted zettel names across
z-yap/zettels/ and fix any found.
- Update
z-yap/tmp/zettel-quality-backlog.md — move the cluster to "Completed".
Process lessons
Patterns learned from prior cluster rework sessions. Apply across all phases.
- Adjacent zettels are often in the same state. Pulling them into scope during a cluster rework produces better results than treating the cluster in isolation.
- User corrections reveal deeper principles. When the user redirects a proposal, listen for the principle behind the correction, not just the surface fix. "That's an independent fact, not a Z3-era artifact" reveals the decouple-from-implementation principle.
- Verify factual claims externally. If a zettel asserts something about PL theory ("eager solving breaks let-polymorphism"), verify via web search before writing it. The ZK must be accurate, not just well-structured.
- The user decides framing, not the agent. Propose actions, but the user chooses the decomposition — splits, merges, reframings the assessment missed. Iterate until told to execute.
- Audit rewrites for prose quality after execution. Bulk rewrites introduce systematic issues (over-aggressive tag removal, blanket negative-framing cleanup, redundant clauses). Re-read each file through the future-reader lens and fix before moving on — catching patterns early prevents compounding across clusters.
- Negative framing requires judgment, not rules. Blanket removal overcorrects (contrasts, erasure facts, domain boundaries are legitimate); blanket keeping under-corrects (status reports survive). Classify each instance individually (see the zettelkasten skill's negative-framing table).
- Overconnecting beats sparsity. A missed connection is a failed search query. Connect to every relevant zettel in the neighborhood, cross-domain especially.
