learning-notes-organizer

Learning Notes Organizer (v3)

Goal

Restructure scattered study notes into a note system with clear boundaries, complete structure, progressive learnability, searchability, and long-term maintainability.

Two-stage workflow (Plan-and-Execute)

Phase 1 — Diagnose & Classify

What to do: Read-only, no writing; produce a structural planning checklist.

Extract the heading tree (H1-H6), and for each heading output a one-sentencemeaningand a one-sentenceguiding annotation("After reading, you will…")
Diagnose issues: duplication/overlap, too broad/too fragmented, unreasonable order (missing prerequisites/advanced content too early), non-standard naming
Propose a new outline (basics→mechanism→practice→pitfalls/optimization, adjusted according to content needs)
Old→new mapping table, with each entry marked with an action label (KEEP/MOVE/MERGE/SPLIT/RENAME/DROP/TBD)
Renaming suggestions (list only those actually needed)
If scope=sections: mark candidate out-of-scope content in the specified sections (coarse-grained; refined in Phase 2)
If scaffold=true: generate the <base>-待整理.md framework file (see Scaffold format for details)

Output: checklist (outline/mapping/renaming/issues), and the scaffold file path + content (if enabled).

Phase 2 — Refactor & Deliver

What to do: Perform refinement rewriting on the content within scope, and handle out-of-scope fragments.

Section refinement: reduce verbosity, enhance coherence, clarify boundaries, keep terminology consistent, and annotate learning-path associations
In-progress out-of-scope routing: during refinement, if fragmentary content that does not belong to the current boundary is found, route it to the correct section (or add a "to be organized" subsection as temporary storage), and generate a routing checklist
Resource tracking (asset_policy=place_correctly_and_track ): zero loss of external links/images; output a resource destination ledger
- Image description detection: scan all image references and detect entries where alt is empty, or alt is only the filename (including extensions such as .png/.jpg), or is a placeholder (such as "insert image description here")
- If ≥1 image lacking a semantic description is found: mark it with ⚠️ ALT_MISSING in the resource ledger G, and prompt at the end of the output: "N images were found to lack semantic descriptions. It is recommended to run /image-alt-title-filler to complete them (already marked in the ledger)"
- Do not call automatically; the user decides whether to run image-alt-title-filler
Minimal changes to sections outside the scope (only allowed to receive routed content; no rewriting)

Output: directly replaceable Markdown + out-of-scope routing checklist + resource ledger (if enabled).

Parameters

Required

target_file: target Markdown file path

Core parameters

Parameter	Allowed values	Default	Description
`scope`	`full` / `sections: ["章节1", ...]`	`full`	Full text or specified sections (supports heading name or path)
`deliverable_mode`	`plan_only` / `full_refactor`	`full_refactor`	Phase 1 only / do both phases
`scaffold`	`true` / `false`	`false`	Whether to generate a pending-organization scaffold file (`plan_only` commonly used when)

Resource strategy

Parameter	Allowed values	Default
`asset_policy`	`place_correctly_and_track` / `preserve_strict`	`place_correctly_and_track`
`asset_ledger`	`required` / `off`	`required`

place_correctly_and_track: External links/images are preferentially placed in semantically appropriate positions; only those marked "prefer deletion" go into 资料参考; the ledger must be output
preserve_strict: Do not move resources, only fix broken link formatting; still output the ledger

Execution steps

deliverable_mode=plan_only

Read: Extract the heading tree + a small number of fragments per section (to determine topic ownership, without reading the full text)
Diagnose: Classify according to the Phase 1 diagnosis
Deliver: Output lists A-D; if scaffold=true, generate the scaffold file

deliverable_mode=full_refactor

Read: Read the full text (or the full text of specified sections + the remaining headings)
Diagnose: Phase 1 diagnosis and classification (a list must first be produced for reference before entering Phase 2)
Refactor: Phase 2 refinement + out-of-scope routing
Deliver: Output lists A-D + refined body text E + routing list F + asset ledger G (if enabled)

Output format

A) New planned outline (including guiding comments)

H1 ...
  H2 ...（引导注释：读完你会…）
    H3 ...

B) Old→new mapping table

Old heading (including level)	Action	New heading path	Image	Notes

Action labels:KEEP / MOVE / MERGE / SPLIT / RENAME / DROP / TBD

Image column:—(no image) / ✓(has image and has alt) / ⚠️(has image but missing alt/title)

C) Renaming suggestions (list only those needed)

`旧标题` → `建议标题`(reason: more standard/shorter/more searchable/more accurate boundaries)

D) Questions to confirm (at most 3-7 items)

E) Refined body text (only when full_refactor)

Output the complete body text (when scope=sections, output only the reconstructed sections, including the necessary parent heading context)
Headings are not automatically numbered; preserve the original emphasis markup (==highlight==, <u>, <mark>, code blocks, etc.)
Append an "Organization Record" block at the end (with F embedded)

F) Out-of-scope routing list (output when full_refactor)

MIG-ID	Source location	Content block summary	Target path	Placement (section/pending organization)

At the same time, append it to the "Organization Record" block at the end of E, to keep a record within the document.

G) Asset destination ledger (output when asset_ledger=required)

Type	Display text/alt	URL/path	Original location	Status	New location	Description

Status:KEPT / MOVED / MERGED / TO_REVIEW / ⚠️ ALT_MISSING(the image is missing a semantic description; it is recommended to use /image-alt-title-filler to complete it)

Scaffold file format (generated when scaffold=true)

Write path: dirname(target_file)/<base>-待整理.md(if it already exists, append -v2/-v3）

Structure:

Top metadata (source file, generation time, description)
New outline and migration workspace (one migration block per new heading)
Appendix A: Old→new mapping table (full)
Appendix B: Renaming suggestions
Appendix C: Questions to confirm
Appendix D: Suggested migration order

Migration block template:

### <新标题>
> 引导注释：<一句话>

**来源旧标题：**
- (MOVE) `旧标题1`
- (MERGE) `旧标题2`

**重命名建议（仅列需要的）：**
- `旧标题2` → `建议标题`（原因：...）

**迁移要点：**
- <注意事项>

⬇️ 在下面粘贴原文内容 ⬇️

（把原文复制到这里）

Execution constraints

Must satisfy

Title auto-numbering disabled (existing numbering in the original is retained)
Retain emphasis markers:==高亮==、<u>、<mark>, bold/italic/strikethrough, inline code, code blocks, blockquotes, Setext headings
Do not change code semantics, do not break code block structure
Zero loss of external links/images: each has a clear destination (body/reference materials/ledger)
资料参考 Only collect resources "leaning toward deletion", and attach "pending manual confirmation" and the reason to each

Not done (non-goals)

Do not perform factual correctness verification
Do not add a large amount of new content
Do not introduce a new numbering system

Invocation template

请按 learning-notes-organizer 执行。

target_file: <path/to/file.md>
scope: full                          # 或 sections: ["章节A", "章节B"]
deliverable_mode: full_refactor      # 或 plan_only
scaffold: false                      # plan_only 时建议 true

asset_policy: place_correctly_and_track
asset_ledger: required

Typical scenario comparison:

Scenario	Parameter combination
Only need a planning checklist and framework files	`deliverable_mode=plan_only, scaffold=true`
Organize the full text directly	`deliverable_mode=full_refactor, scope=full`
Organize only a few specified chapters	`deliverable_mode=full_refactor, scope=sections:[...]`

Self-evolution

This skill supports progressive evolution. When behavioral deviations are found in practice, refer to EVOLUTION.md protocol to perform iterative upgrades.