tag-organize

Core principles and workflow for organizing note tags

Core principles

Organizing tags is not about executing a standard methodology, but about serving a specific person. There is no unified "correct" way to classify; all decisions are based on the user's actual needs.

The value of organizing comes from only three directions, and any change that cannot bring about any one of them is not worth doing:

Improve usage efficiency: reduce maintenance burden, lower classification anxiety
Improve retrieval efficiency: let users find target content faster
Bring new perspectives for knowledge connections: discover associations that were previously invisible

Do not ask the user at the start of the task "what scope do you want to organize, and how do you want to organize it". When a user asks AI to organize, it itself means he does not want to make these judgments himself. AI's responsibility is to proactively provide specific options, letting the user choose from multiple-choice questions, not answer essay questions.

Operational safety constraints

At the current stage, only tagging is done. Note tags are file-level independent objects, added, deleted, and modified through the wps-note dedicated tool manage_note_tags ; do not modify tags again through edit_block、batch_edit or <tag> XML.

Hard rules that must be followed for every operation:

Use only manage_note_tags：
- to modify tags. Query a note's current tags:manage_note_tags({ note_id })(passing only note_id is a query)
- Add:manage_note_tags({ note_id, add: ["工作/项目"] })
- Delete:manage_note_tags({ note_id, remove: ["旧标签"] })
- Rename / merge: combine in the same call remove + add
- Tag names passed to the tool do not carry the # prefix;#工作/项目 is only used as the customary notation when displaying to users
Global operations across notes must first ask_user confirm: global renaming, merging, and batch deletion of tags (affecting 2 or more notes) are cross-note batch operations, and before execution ask_user。
must be called. Notes with unclear intent should be skipped directly: when the content topic or purpose cannot be determined, do not guess, do not modify, and list them as "unprocessed" in the plan to inform the user.
Do not delete any notes: no matter how empty a note looks, do not delete any notes at this stage.
Confirmation must use the ask_user tool: it is forbidden to use text questions instead of ask_user calls—text questions will not pause execution, and the user cannot intervene. In the same round as calling ask_user , it is forbidden to execute write tools.

WPS Notes system behavior explanation

When operating in WPS Notes, the following system behaviors will affect the results and must be understood:

Behavior	Description	Response method
`/` indicates hierarchy separation	In tag names, `/` is a hierarchy separator, and WPS automatically parses it as a parent-child relationship	Write the full path and call `manage_note_tags({ note_id, add: ["工作/项目"] })`
Case-sensitive	Tags are stored as entered by the user,`TODO`、`Todo`、`todo` are three different tags	When comparing tags, compare literally, without case normalization
Tag input restrictions	At most 10 levels of hierarchy, each level at most 20 characters; disable `\ : * ? " < > \|` and emoji; duplicate tags are not allowed within the same document	When generating new tags, proactively comply with these restrictions; if a system error is hit, adjust according to the returned information and retry

Task workflow

第一步：全局概览，判断健康度
    ↓
第二步：分析与诊断
    ↓
第三步：给出具体方案  ──→  [结论：不需要整理] → 说明理由，结束
    ↓
第四步：用户确认  ──→  [有异议] → 修改方案，回到第四步
    ↓
第五步：执行
    ↓
第六步：回顾检查  ──→  [有偏差] → 修正，重新检查

Step 1: Global overview, assess health

Select appropriate tools to view the current note files and tag list, understand the overall status of the current note system, and then decide where to dig deeper.

First layer: mandatory (global overview)

get_note_stats({ detailed: true }) — get in one call:
- Total number of files, total number of tags, number of untagged files
- Distribution of the number of files under each tag (in descending order by note count, returning at most 30; when there are many tags, combine with find_tags() to see the full set)
- List of recently updated files
find_tags() — get:
- Complete tag hierarchy structure (parent-child relationships, naming)
- Identify naming style, hierarchy logic, suspicious tag names

After completing these two steps, you can usually already discover most problems (imbalanced granularity, inconsistent naming, too many untagged files, etc.) and form a preliminary judgment on the direction of organization.

Second layer: investigate as needed (for discovered problems)

Based on the clues found in the first layer, use the following tools as needed for targeted investigation:

What you want to know	Which tool to use
Which files are under a suspicious tag	`search_notes({ tags: ["标签名"] })`
Which files are untagged	`get_note_info({ limit, page })` paginated query, filter notes with `tags` empty
Which tags a certain note currently has	`manage_note_tags({ note_id })`(passing only note_id is a query)
What a certain file is roughly about	`get_note_outline({ note_id })`
The precise content of certain blocks of a certain file	`read_blocks({ note_id, block_ids })`
The complete content of a certain file (when deep understanding of the content is needed)	`read_note({ note_id })`, without `max_length` restriction

Principle: use the lightest tool that satisfies the current need：get_note_outline When it can locate, prefer to use it;search_notes({ tags: [...] }) When it can filter, prefer to use it; only use read_note。

Step 2: Analysis and diagnosis

On the basis of complete information, identify the user's categorization habits, andcheck item by item against the problem diagnosis table below。

Existing habits are valuable assets, not problems that need correcting. If the user already has fixed habits and the classification logic is reasonable,do not easily break them。

During analysis, also think in conjunction with the note content: why did the user save each note? What scenario does it serve? What keywords will be used to retrieve it in the future? This determines whether the tag has real retrieval value.

Prerequisite judgment: too few tags, unable to diagnose

When there are very few existing tags, it is insufficient to judge the user's classification preferences. In this case, skip the following diagnosis and instead, based on the note content,design a tag system for the user from scratch。

→ Consult references/classification-methods.md, choose an appropriate classification method from it according to the user scenario (hierarchical classification method / P.A.R.A. / entity-scenario method), and in step 3clearly state the reason for the choiceso the user can confirm. When uncertain, recommend by defaultHierarchical classification(most broadly applicable, easiest to get started with).

Problem diagnosis table

1. Duplicate / semantically identical

	Description
Normal state	A concept has only one tag
Problem manifestation	`待办`、`TODO`、`to-do` coexist;`AI` and `人工智能` coexist;`会议` and `meeting` coexist
Handling suggestion	Merge into the one more commonly used by users; after the original tag loses all references, the system automatically cleans it up

2. Unreasonable hierarchical structure

	Description
Normal state	The parent-child relationship is semantically valid (the child tag is a concretization of the parent tag); tags at the same level are truly parallel concepts; the number of tags at each level is moderate, and the depth of the hierarchy has practical meaning
Problem manifestation (hierarchical misplacement)	Parallel concepts are mistakenly placed as a parent-child relationship:`学习/数学/语文`，`数学` and `语文` are parallel disciplines,`语文` should not be placed under `数学` Below
Problem manifestation (too many at the same level)	A level contains dozens of tags all laid out flat, without any grouping, and the tag list is lengthy—in this case, similar tags should be grouped under a common parent tag
Problem manifestation (redundant hierarchy)	A level contains only one tag, the intermediate level has no other parallel items, and it does not provide additional filtering value—in this case, the intermediate level should be merged or removed
Judgment method	Ask at each level: "What is the meaning of this level? What concepts might be parallel to it in the future?" A level that cannot be answered should not exist; when there are many tags at the same level, consider whether there is a common parent under which they can be categorized
Handling suggestion	Hierarchical misplacement → correct the parent-child relationship; too many at the same level → identify common attributes and create a parent tag for categorization; redundant hierarchy → merge or remove the intermediate level

3. Imbalanced tag granularity

	Description
Normal state	The number of files associated with each tag is moderate and can filter effectively (neither too broad nor too fine)
Problem manifestation (too fine)	A tag is associated with only 1-2 files, and these files are already covered by a more appropriate parent tag—this tag is redundant
Problem manifestation (too broad)	A tag is associated with a large number of files, and after opening it, it is almost equivalent to "all notes," providing no filtering value during retrieval
Handling suggestion	Too fine → merge into the parent tag or a similar tag; too broad → split into child tags and guide users to use more precise classification

4. Inconsistent naming style

	Description
Normal state	Tags at the same level have a consistent naming style (consistent part of speech, language, and capitalization)
Problem manifestation	Among tags at the same level, some use nouns and some use verbs; Chinese and English are mixed; full-width and half-width symbols are mixed; English capitalization is inconsistent
Handling suggestion	Unify based on the style of the majority of the user's existing tags; the naming style itself has no right or wrong, as long as it is unified

5. Uneven note coverage

	Description
Normal state	Most notes have tags, and the tag system can cover the user's main content types
Problem manifestation	A large number of notes have no tags at all, or a certain type of content (such as recently added notes) systematically lacks tags
Handling suggestion	Add tags to untagged notes; when the gap is too large, prioritize the most commonly used and most important content

If none of the above problems exist: → Proceed to step three, directly tell the user "it is recommended to maintain the status quo" and explain the reason.

Step three: Provide a specific plan

Directly present the target tag system structure after the changes, with the reason for each change attached—present the target state in full so the user can compare and judge.

Plan format example:

建议改动后的标签体系：

工作
├── 项目            ← 原 项目A、项目B 统一归入此处
└── 日常            ← 原 工作记录 改为此，更简洁

学习               ← 原 读书 和 网课 合并入此
├── 读书
└── 网课

生活               ← 保持不变

待办               ← 原 TODO、to-do 合并为此（用户最常用的写法）

未处理：「未命名笔记」「未命名笔记(1)」（内容为空或无法判断意图，请用户自行决定）

Case one: Only a small number of changes are needed

→ Directly list the specific changes, explain the reasons, and proceed to step four for confirmation.

Case two: A relatively large-scale rebuild is needed

→ First present the overall target structure, then list the main change points, so the user can judge the whole picture before confirming.

Step four: User confirmation

Through ask_user tool to obtain user confirmation.

Case one: The user agrees

→ Proceed to step five for execution.

Case two: The user raises objections or doubts

→ Rethink the plan. The user's doubts usually point to places in the plan where the logic is not self-consistent. Revise accordingly, present it again, and return to step four.

Case three: The user partially agrees

→ Execute only the part the user confirmed, suspend the doubtful part, and wait for further confirmation from the user.

Step five: Execution

Execute the changes according to the confirmed plan.

Judging the execution scale:

Few changes (single digits) → complete in one go
Many changes → execute in batches, with each batch divided by logical unit (for example: first handle global merge operations, then handle individual note adjustments)

Step six: Review and check

After execution is complete, proactively verify the results.

Two levels must be verified:

Tags of the target notes: From manage_note_tags Check the return value of the write operation—tags is the complete updated tag list,added / removed is the item that actually took effect; confirm that the target tag is in tags and that the hierarchy is correctly reflected with / correctly reflects
System tag list（find_tags()): Confirm that new tags have been created, that merged/deleted old tags have disappeared, and that the overall structure conforms to the plan

Case one: The result matches expectations

→ Present a summary of the changes to the user, explaining whether there are any remaining issues (for example, the reason certain notes were skipped).

Case two: A deviation is found

→ Find the cause, correct it, and recheck until the result matches expectations before reporting to the user.