The goal is to keep important information at the appropriate layer, with only one maintainable source of truth, still accurate and findable.
First determine the task mode
- Diagnosis or health check: read-only inspection, providing evidence and a candidate list.
- Setup or refactoring: first understand the existing project and entry points, then propose a reviewable structural plan.
- Execute organization: make changes within the scope explicitly authorized by the user; for deletions or bulk moves with unclear scope, provide a specific list first.
- Single write: determine whether it should be written to Memory, documentation, a Skill, or configuration; no need to run the full scan.
When the user explicitly specifies how a piece of content should be retained, moved, or deleted, the current instruction takes precedence. Do not override the user's choice with a Skill's default process.
Four questions
Apply uniform judgment to Memory entries, documentation, Skills, and pointers:
- Which layer does it live in: is this a long-term preference, project fact, reusable process, or environment configuration?
- Where is the source of truth: which location is responsible for updates? Are other locations just indexes or outdated copies?
- Is it still accurate: can paths, links, numbers, versions, and project status be verified on the spot?
- Is it findable: are the entry points sufficient for people and Agents to locate it quickly? Only add an index when real navigation difficulties exist.
Layering principles
- Skill: repeatable methods, domain rules, and tool processes.
- Project documentation: project facts, decisions, materials, outputs, and history.
- Memory: preferences, current state, and short pointers frequently needed across sessions.
- Configuration files or secret storage: credentials, runtime parameters, and environment facts.
Set only one source of truth for a piece of information. Other layers may keep brief pointers, but do not copy the body text. Memory's capacity should be determined by retrieval value; do not treat it as a complete database.
Maintenance process
When doing a directory or knowledge base health check:
-
Clarify the scan scope and the current task; do not expand to the entire workspace by default.
-
Run a read-only scan on the directory:
python3 scripts/scan.py <目标目录> [--depth 2] [--compact] -
Explain candidate items in light of actual content. Scripts finding duplicate names, missing READMEs, or scattered files does not mean they must be deleted or moved.
-
Output the candidate items that need handling: duplicates or zombies, information that should be migrated, and stale pointers. For each item, explain the evidence, target location, and risk.
-
Execute changes that have been explicitly authorized; deletions, overwrites, or bulk migrations with unclear scope require the user to confirm a specific list first.
-
After changes, re-verify pointers, entry points, and sources of truth; do not repeat a full scan just to pad the process.
For detailed maintenance steps, see references/scan-workflow.md. Only read references/folder-rules.md。
Setup process
When setting up from scratch or doing a major refactor, read references/setup-guide.md. First infer the structure from existing READMEs, directories, and Memory; ask questions only when missing information would change the plan.
Do not force every directory to have a README, and do not decide whether documentation needs sections based on a fixed line count. The complexity of indexes and layering should be commensurate with the actual lookup cost.
Security and Authenticity
- Do not write complete keys, Tokens, or sensitive credentials into Memory, documents, or reports.
- Project completion status cannot be inferred solely from inactivity, departure, or discontinued updates; if handling depends on that status, list it as a fact to be confirmed.
- "Downgrading" means moving details to the appropriate source of truth and retaining necessary pointers, not making information that still has value disappear.
- Before deleting existing content, confirm the target and the source of truth; when the user has already explicitly named and authorized the deletion, do not repeatedly ask for the same confirmation.
- Verify external links, cloud documents, and scheduled tasks preferentially in a read-only manner.
Experience and Evaluation
Read this only when historical incidents need to be investigated or this Skill needs to be maintained references/pitfalls.md, and do not load the entire case library into ordinary governance tasks.
Completion criteria: the user can explain where important information is updated; duplicate rules are reduced; key pointers are valid; unauthorized content has not been moved or deleted; the report does not leak credentials.