section-refactor-with-todo-routing

Section Refactor with Todo Routing (v2)

Purpose

Without having to refactor the entire document, accomplish three things:

1. Global navigation: Extract all headings in the file (H1-H6), and for each heading output:
   • A one-sentence "meaning/what this section covers"
   • A one-sentence "guidance annotation: after reading you will..."
2. Local refactoring: Refactor and organize only the user-specified sections (1~N, variable) (trim verbosity, improve coherence, clarify boundaries, make the learning path smoother, keep terminology consistent).
3. Out-of-bounds content routing: If a specified section contains content blocks that do not belong within that section's boundaries:
   • Route them to a more appropriate target heading;
   • If the target heading lacks a suitable container or the content needs to be temporarily stored, add a subheading under that target heading 待整理 and place the content in it;
   • making it easy for the user to later "name a to-be-organized module" and continue organizing it.

Dependencies

• $learning-notes-organizer
  • Used for boundary judgment, categorization, learning paths, refined rewriting, format fidelity, and other specifications (this skill does not repeat the detailed rules)
• $planning-with-files
  • Used to organize the execution flow and delivery structure (extract → plan → map → deliver)

---

Input

Required:

• target_file: Path to the target Markdown file
• focus_sections: List of sections to refactor (1~N, variable)
  • Supports: heading name (fuzzy) or heading path (exact)
  • Example:
    • ["学习资源与概览", "核心概念与内存背景"]
    • ["核心概念与内存背景/ByteBuf", "Pipeline/Handler"]

Optional parameters (new in v2, recommended to just use defaults):

Read/extract

• heading_level_support: Default H1-H6
• meaning_source: "title_plus_snippets" | "full_text"
  • Default "title_plus_snippets"(meaning/guidance annotations based on heading + a small amount of content)
• intro_policy: "prefer_existing_then_generate" | "generate_if_missing" | "existing_only"
  • Default "prefer_existing_then_generate"

Matching strategy

• section_match_policy: "prefer_path_then_title" | "title_only"
  • Default "prefer_path_then_title"
• duplicate_title_policy: "ask_tbd" | "pick_best_match_with_reason"
  • Default "pick_best_match_with_reason"(and explain the matching rationale in the summary; mark TBD if truly uncertain)

Out-of-bounds content and to-be-organized containers

• routing_unit: "subsection" | "paragraph_block"
  • Default "paragraph_block"(finer granularity; move by subsection when necessary)
• todo_bucket_name: Default "待整理"
• add_todo_bucket_policy: "only_when_needed" | "always_when_routing"
  • Default "only_when_needed"
• todo_insert_position: "top_of_target_section" | "bottom_of_target_section"
  • Default "top_of_target_section"(more prominent)

Out-of-scope change policy

• outside_scope_edit_policy: "minimal_only" | "allow_small_fixes"
  • Default "minimal_only"
  • minimal_only: only allowed to add to-be-organized containers under the target heading and insert migrated content
  • allow_small_fixes: on top of minimal, allows small fixes (broken links/terminology consistency/necessary transitions), but must not expand into out-of-scope rewriting

Traceable markers (to make it easy to name and continue organizing later)

• migration_id_policy: "auto_ids" | "none"
  • Default "auto_ids"(generate referenceable IDs for migrated content blocks)

---

Execution steps (must be output according to $planning-with-files)

Step 1 — Extract

• Extract the complete heading tree (H1-H6, including hierarchical paths)
• For each heading output:
  • Meaning: A one-sentence "what this section covers"
  • Guidance annotation: One sentence "After reading you will..."
• Guide annotation generation to follow intro_policy

Step 2 — Plan

• Only for focus_sections：
  • Provide section boundaries (what should be included/excluded)
  • Adjust internal structure and order (basics → mechanisms → practice → pitfalls/optimization; as content requires)
  • Mark out-of-bounds content blocks (by routing_unit）

Step 3 — Map

• For content blocks within the specified section:
  • Old position → new position (reorder within the same section)
• For out-of-bounds content blocks:
  • Source position → target heading path
  • If the target heading lacks a suitable container or needs temporary storage:
    • Add subheading 待整理(by todo_bucket_name）
    • Place the content into that 待整理(by todo_insert_position）
• If migration_id_policy=auto_ids：
  • Generate for each migrated content block MIG-xxx markers, to facilitate later follow-up organization by name

Step 4 — Deliver

• Output "full heading index + meaning + guide annotations"
• Output "the final Markdown after restructuring the specified section" (can be directly replaced back into the original file)
• Output "migration and pending-organization addition list" (traceable, reviewable)
• Output "change summary"

---

Deliverable format (must include)

A) Full heading index (H1-H6) + meaning + guide annotations

• Display in a tree hierarchy (clear paths)
• Each heading has at least two lines:
  • 含义：...
  • 引导注释：...

B) Restructuring result for the specified section (directly replaceable Markdown)

• Output only the restructured section (including necessary parent heading context)
• Headings are not automatically numbered; emphasis markers/code block structure should be preserved as faithfully as possible (detailed rules are managed by learning-notes-organizer)

C) Out-of-bounds content routing list (migrated out of the specified section)

MIG-ID	Source position (section/subsection)	Brief description of content block	Target heading path	Destination (target heading/pending organization)

D) New 待整理 list

Target heading path	Whether to add 待整理	Insertion position (bottom)	Which MIG-ID/content blocks were placed

Invocation template (recommended)

使用 $section-refactor-with-todo-routing（v2）
target_file: <path/to/file.md>
focus_sections: ["章节1", "章节2", ...]
# 可选：
outside_scope_edit_policy: minimal_only
add_todo_bucket_policy: only_when_needed
migration_id_policy: auto_ids