Andy-zch/agent-skills

Project Logic Map

Help maintainers and AI answer: What to change, what is affected, what must not be broken, and how to verify.

Select Task Scope

• Initial Generation: Based on requirements and code forensics, generate a Markdown relationship map. When the user needs a visual browse or already has HTML, also generate or maintain a visual diagram.
• Incremental Update: Keep stable IDs, only update changed facts, relationships, statuses, and diagrams. Check for references to deleted nodes.
• Impact Analysis: Trace inputs, consumers, statuses, exception branches, constraints, and validation around a given change; when the user only asks for analysis, do not implement changes.

Prioritize using the project's existing files and IDs. New projects default to outputting docs/LOGIC_MAP.md; the visual version defaults to docs/logic-map.html. Prefer existing naming or user-specified locations.

Gather Evidence First, Then Build Relationships

Read the project conventions, requirements baseline, key entry points, pages/workspaces, state and storage, business flows, tests, and release notes. Follow core user tasks to read necessary code; do not exhaustively enumerate every file in the repository.

Clearly distinguish: promised requirements, actual implementation, automated check evidence, runtime environment verification, and external audits. Mark old records with dates and evidence scope; checks not executed cannot be documented as passed.

Focus on tracking:

• Whether multiple entry points truly share the same processing chain, and which bypass certain steps.
• Who creates, holds, consumes, overwrites, and releases data; whether it persists or leaves the local machine.
• How cancel, empty data, rejection, over-limit, and parsing failure each terminate.
• Whether high-frequency updates, batches, thresholds, etc., carry project-specific invariants.

When documentation conflicts with code, record both separately; do not forcibly merge for aesthetic purposes. If code risks are found, they can be written as gaps, but do not automatically expand the task into a fix.

Build a Traceable Model

Read references/model.md and adopt its nodes, relationships, and evidence fields; simplify or adjust based on the project's existing numbering.

Start with a one-sentence definition and main chain for the core task, then supplement normal/exception branches, cross-page states, interfaces, constraints, and validation. Adjacent on a diagram does not imply a relationship; every edge must explain its meaning and basis.

Default delivery structure:

1. Capability Overview: Let the reader know what the product can do first. Group by real user tasks; do not count the number of technical sub-diagrams as the number of capabilities, nor fix to five groups as in this example.
2. Individual Capability Flow: Expand entry points, actions, processing, states, and exits; label branch conditions.
3. Node Description and Evidence: Responsibilities, direct relationships, implementation location, constraints, validation, and status.
4. Change Impact Index: Common changes corresponding to which nodes, files, and checks.

The overview may omit secondary relationships, but the complete model or node descriptions must be retrievable. The requirements document continues to serve as the authority for requirements; the map should not establish a separate requirements baseline.

HTML Visual Delivery

When HTML is needed, read references/visual.md. If specific reference is needed, also check references/wechat-example.html; it is an example from an implemented project, not a universal fact or fixed layout template.

Let nodes and semantic edges share the same data. Manage view coordinates, routing, and themes separately; use the same IDs for Markdown and HTML. Simple projects can directly maintain a small data structure without forcing a generator or graphics library.

Preserve visual directions already confirmed by the user. Default to centered with limited width, capability overview entry point, individual capability flow navigation, descriptions below the diagram, and light/dark dual themes. Node count and diagram subdivision are determined by content density.

Do not copy the example's WeChat-specific terms, size thresholds, pending state, or manual coordinates to other projects. When a product root grouping is only for display structure, clearly mark it and do not treat it as a new business capability.

Validation and Delivery

Content and structure:

• IDs are unique; edge endpoints exist; key capabilities have drill-down entry points; no dangling references after node deletion.
• Include, data flow, dependency, constraint, and validation each have their own semantics; do not mix them into an execution order.
• Storage lifecycle, exception exits, implementation locations, and states can be supported by evidence.
• Ask once about a specific change, e.g., "What would changing the layout affect?", the map should trace to the relevant states, consumers, and validation.

The visual version also requires an actual browser check:

• The overview displays all major capabilities simultaneously, text is clear, and arrows do not cross nodes or text.
• Open each capability flow individually, verify drill-down, cross-diagram associations, selection state, and deselection.
• Check the light and dark text, nodes, lines, arrows, and descriptions; capture screenshots.
• Check the overview completeness at the target desktop size; on narrow windows, maintain readable font size, allow scrolling within the diagram or switching to separate diagrams.

Static syntax or structure checks cannot replace visual checks. When the browser is unavailable, deliver the file and clearly note the incomplete checks; do not substitute old screenshots as current results.

Deliver links, major relationship changes, actual check results, and remaining gaps. Save work according to the project's Git conventions; do not self-publish to websites or install global skills.