project-memory

Project Organization

This skill defines change detection, maintenance order, boundary constraints, and logging requirements for project organization.

🎯 Goals

• Continuously maintain post-production resources such as project documents, themes, and data without duplicating work
• Keep project asset structure clear, traceable, and progressively extensible
• Record maintenance actions through logs to provide a basis for future collaboration

🔍 Change Detection (Incremental Scan)

When performing project organization, first performincremental change detection, rather than full maintenance.

Scope Determination

The user may include a scope description, and the Agent needs to determine the scan scope according to the following priority:

1. User explicitly specifies scope: The user directly identifies the target, for example:
   • "Help me organize the homepage-related documents" → scan only the homepage prototype and its associated resources
   • "Sync the themes and data" → scan only src/themes/ and src/database/
   • "Update the documents for xxx-page" → scan only that prototype and its associated documents
2. User vague description: The user gives a direction but does not specify precisely, for example:
   • "Help me organize the pages I changed recently" → scan recently changed prototypes/components by timestamp
   • "Update all the documents" → scan all documents and their associated prototype changes
3. User does not specify scope (default): perform a full incremental scan (see the default detection process below)

Default Detection Process

When the user does not specify a scope, perform the following default process:

1. Read the last execution time: from src/docs/memory-log.md get the timestamp of the last log entry
2. Scan changed files: use that timestamp as the baseline to detect files changed since the last execution
   • Default scan scope:src/components/、src/prototypes/、src/themes/、src/database/、src/docs/、src/common/
   • Use find or git diff --name-only and other methods to obtain the list of changed files
3. Classify changes: classify changed files by type
   • Prototype / component changes (src/prototypes/、src/components/）
   • Document changes (src/docs/）
   • Theme changes (src/themes/）
   • Data changes (src/database/）
   • Common module changes (src/common/）
4. Generate a suggestion list: based on association analysis of changed files, provide suggestions for updates

Suggestion List Format

Present the change detection results to the user in the following format:

📋 上次项目整理：YYYY-MM-DD HH:mm
📝 检测到以下变更：

🔸 原型/组件变更：
  - xxx-page（新增 / 修改）
  - yyy-component（修改）

🔸 建议更新：
  - [ ] 更新 project-overview.md 索引（新增了 xxx-page）
  - [ ] 更新 page-map.md（页面结构变化）
  - [ ] 同步 xxx 主题配置（关联组件已变更）
  - [ ] 更新 orders.json 数据（页面数据源变化）

是否按以上建议执行？

First Execution

If memory-log.md does not exist or is empty (first execution), perform a full scan and suggest initializing all post-production resources.

🚦 Execution Boundaries

• Project organization only handles post-completion supplementary work after pages or prototypes are completed
• Do not go back and redo pages, prototypes, or their main implementation
• If the existing document structure is unreasonable, subdocuments may be merged, split, or added, but the traceability of the main entry point must be preserved
• Only update post-production resources related to changed files; do not perform irrelevant full refreshes
• When communicating with users, prefer natural expressions such as "I can continue to help you organize and remember xxx"

🧭 Fixed maintenance order

After the user confirms the suggestion list, execute in the following order (only perform steps related to the changes):

1. Git snapshot

• First check whether the project has Git version control enabled
• If it is a Git repository and there are uncommitted changes, first commit the current uncommitted version
• If there are no uncommitted changes, skip
• Fixed format for snapshot commit message:

chore: snapshot before project-memory <YYYY-MM-DD HH:mm>

2. Project description entry point

• Check whether src/docs/project-overview.md exists
• If it does not exist, create it based on the template
• If it exists, thenonly update the parts related to this change(such as adding a page index, adjusting the reading order, etc.)
• src/docs/project-overview.md must remain lightweight, and only assume the responsibilities of "project overview + reading index + key to-dos"
• It is recommended to check the file line count once during each maintenance
• When any of the following situations occurs in this file, it must be reorganized and optimized:
  • The file line count has reached or exceeded 1000 lines
  • It is clearly possible to split it into topic subdocuments and then have the main entry point serve as an index
• Optimization principle: prefer the method of "package splitting + summary aggregation"; retain high-value summaries, migrate details to topic subdocuments, and keep only the index, conclusions, and necessary to-dos in the main entry point; do not use simple deletion-based compression to handle the main document
• Optimization goal: by splitting topic documents and converging summaries, the main entry point should preferably be kept within 800 lines

3. Subdocument maintenance

• Only maintain topic subdocuments related to this change
• Determine which subdocuments need updating based on the change detection results
• Prefer to maintain the following suggested documents (as needed):
  • page-map.md
  • information-architecture.md
  • business-flow.md
  • data-model.md
  • permission-model.md
  • state-lifecycle.md

4. Topic maintenance

• Execute only when change detection finds topic-related changes
• If the project already has topics, update the topic documents, topic index, and related references
• If the project does not yet have topics, but the current scenario requires topic support, create a minimal topic skeleton
• Default topic maintenance location:src/themes/

5. Data maintenance

• Execute only when change detection finds data-related changes
• Update src/database/ data related to pages, documents, and topics
• Data files must follow src/database/README.md
• After maintenance, the data index in the main entry point must also be updated

6. Maintenance log

• A maintenance log must be appended after every project organization
• Default log file:src/docs/memory-log.md
• Log template source:src/docs/templates/memory-log-template.md
• The log uses a compact format, one entry per line, avoiding long natural-language descriptions
• When src/docs/memory-log.md reaches or exceeds 1000 lines, you must first delete the oldest 100 lines of business logs, then append a trim log recording this trimming action, and finally write this maintenance log
• Trimming logs are also formal logs and cannot be omitted
• Except when the above trimming rules are triggered, logs are only appended, and history is not rewritten

📝 Log format

The log is fixed as a single line, with fields in the following order:

YYYY-MM-DD HH:mm | kind | sum | doc | theme | data | git | todo

Field requirements:

• kind：upd indicates regular maintenance,trim indicates log trimming
• sum: update summary, preferably kept within 20 characters
• doc: For document changes, write only the file name, topic name, or -
• theme: For topic changes, write only the topic name, directory name, or -
• data: For data changes, write only the data file name, table name, or -
• git: Short commit hash or -
• todo: Follow-up to-do or -

Recording principles:

• If short words suffice, do not use long sentences; if a file name suffices, do not use explanatory paragraphs
• For unchanged fields, uniformly write -
• If there are many changes at once, prioritize recording the key indexes of "entry document / topic / data", and do not expand details in the log

Example:

2026-03-16 14:20 | upd | 更新总览索引 | project-overview,page-map | - | orders.json | a1b2c3d | 补权限模型
2026-03-16 14:25 | trim | 删旧100行 | - | - | - | - | 保留较新记录

✨ Quality checkpoints

• Incremental change detection has been performed and the suggested list has been displayed
• The user has confirmed the suggested list
• If it is a git repository and there are uncommitted changes, a snapshot commit has been made first
• Checked or maintained src/docs/project-overview.md(only the changed relevant parts)
• Topic subdocument structure adjusted as needed (only the changed relevant parts)
• Topics and data synchronized and maintained (only the changed relevant parts)
• Appended in compact format src/docs/memory-log.md