Produce specifications that product, design, development, and testing can use together:User goal → Feature → Page → Operation → State change → Result → Acceptance evidence. Pages, buttons, and exception branches should all have business ownership, avoiding claiming complete design with a few normal-state screenshots.
The core deliverables are three main lines:A complete feature list with module-by-module detailed specifications, a workable interaction flow, and a directly handoff-ready page-by-page interface structure, and then derive planned tasks from them. First read Fixed Working Method, and execute according to its steps. The number of files, JSON validation, or a few design diagrams must not replace depth of content.
Mandatory Delivery Contract
A complete organization and planning request must first read Fixed Delivery Contract v1, and execute in order source → feature → navigation → flow → Surface → task → review, and must not arbitrarily remove stages, merge delivery files, or omit required fields. The task plan is a mandatory deliverable. Existing specifications/tasks serve as the single source of truth, and this skill's output provides a structured tracking view.
Create the fixed seven Markdown documents and delivery.jsonaccording to the contract; when existing files are present, reference and complete them without overwriting human decisions. Read Fixed Document TemplatesandReview Checklist. Finally execute python3 <skill>/scripts/validate_delivery.py <PACKAGE> --require-ready, and only after passing is it permitted to report "organized according to the fixed pattern complete." Semantic review cannot be replaced by script passing, and unresolved blockers must be retained.
Must reference existing deliverables
The first complete organization must read Example Reading Guide、Example Project A original deliverable excerptsand Example Project A import participants running example, and follow 00–06 to learn the unfolding process from real features to interfaces, interactions, and tasks.Example Project A P02 exampleis used for comparison with another business chain;Example Project B teaching packageis referenced only when it is necessary to understand the organization of fixed files and machine indexes. When continuing an existing project, also read continuation example. Do not copy example menus, technology stacks, quantities, rules to be confirmed, or review passes; examples are not the source of truth for the target project's requirements.
Determine mode and authorization
- "How to do/review/explain": methods or read-only review may be given in the reply, and files are not created merely because the skill is triggered.
- "Organize/output plan/write documents": write to the directory specified by the user; if unspecified, continue the project's document organization, and first report the proposed delivery location.
- Existing specifications: continue from existing deliverables, preserving IDs, human modifications, and execution status. Read-only reference repositories are used to extract methods, and their business requirements or statuses are not migrated in.
- Visual generation, business implementation, tool installation, specification system initialization, and submission/release are each constrained by the current authorization; this skill does not automatically start these stages.
1. Establish evidence and scope
Confirm the target repository, branch/workspace, and applicable instructions; identify OpenSpec, Spec Kit, or an existing design process. A single change has only one source of truth for specifications; do not create a separate task system. Use the existing semantic index to locate implementations as needed; do not automatically install or initialize tools for documentation tasks.
Establish a brief source table: source/location/date/applicable version/supported conclusions/evidence level. Distinguish user confirmation, current specifications, source code facts, runtime evidence, target design, old prototypes, and historical completion claims. Read only the necessary representative files and trace along references; claiming "reviewed everything" requires a complete coverage record.
When conflicts arise, register the basis and impact for both sides. A later file, a title containing "final", or a prettier prototype is not sufficient to prove that confirmed decisions have been superseded. Explicit new user decisions take precedence; when it cannot be determined, retain the existing confirmed scope and mark new suggestions as proposals. Ask questions only about key ambiguities that affect subsequent work; continue organizing the rest.
2. Build the feature list from business goals
First clarify users/roles, objects, scope, states, trigger conditions, and observable results, then define pages. You must first write the full feature master table, then expand detailed specifications module by module according to the ten items of the fixed working method; each feature includes a stable ID, user goal, preconditions, inputs/outputs, permission scope, main path, exceptions and recovery, associated pages, acceptance, source, and maturity. A table with only module names, feature names, and priorities is unqualified.
Verify behavior using known interfaces; when there is no implementation yet, write target use cases and do not fabricate commands or APIs. When a button changes business state, make clear the distinction between submission, acceptance, execution, success, and unknown. "File exists/process online/request returned/page prompt" must not be treated as the final business result.
3. Information architecture and page structure
Distinguish product surfaces, global shell, business domains, navigation entries, pages, local tabs, and action layers. Details, wizards, and confirmations are not naturally first-level menus. Clearly state the object context and, after switching, which data/drafts are retained, cleared, or revalidated.
For each page, explain the question the user needs to answer, the entry and exit paths, and the content structure from top to bottom/left to right, primary and secondary actions, scroll areas, focus, and empty/failure states. Each main page or structurally different subpage must have a layout partition table or textual wireframe, listing real fields and actions; writing only "top + sidebar + content area" is unqualified. Use Mermaid to express information architecture, cross-page flows, and complex state machines; diagrams must reference actual page/feature IDs, not merely draw abstract technical layers.
Do not treat the sample project's fixed menus, roles, screen counts, viewports, drawer widths, or visual style as universal rules.
4. Expand user flows and interaction surfaces
Each core journey covers: entry → precondition check → input → preview/necessary approval → submit → processing → result → next destination; supplement as needed by business with cancellation, failure, offline, conflict, rejection, interruption, and recovery. Mark irrelevant branches as "not applicable + reason"; do not mechanically add confirmation to every button.
The main-chain diagram must be accompanied by an operation-by-operation transition table: starting point, action, validation, business change, success/failure destination, cancellation/return and data retention. A diagram with no error branches, button destinations written as "per Registry" without actually finding out, or task execution order passed off as user flow is unqualified.
Continue using existing numbering and explicitly register types and parent relationships in the machine index; new projects uniformly use P01 main pages,P01-01 subviews,P01-A01 actions,P01-S01 status,P01-E01 blocking,P01-R01 results,G01 global interaction. IDs are semantic locators and do not mean that a full-page mockup must be drawn.
Create a separate ID when the business information structure changes, new wizard steps are added, an independent Drawer/Modal is used, permissions or high-risk decisions are involved, or important errors/results occur. Place ordinary pagination, hover/focus, Tooltips, and Skeletons with no business differences on the component state board to prevent splitting for the sake of increasing the count.
Each Surface uses thetemplateto define triggers, prerequisites, context, required information, primary/secondary actions, state transitions, success/failure destinations, return behavior, and acceptance. It is not acceptable to merely list "loading/error/success" without describing the specific content and executable next steps.
5. Cross-platform and design dependencies
If multiple interface implementations exist, first follow user requirements to determine "business equivalence" or "visual and interaction consistency." When consistency is required, fix the common navigation, content, assets, states, copy, and action contract; different technical components cannot be a reason to arbitrarily change the interface.
Describe shell/parent page dependencies at the delivery granularity: new pages establish the content structure; state variants inherit from the parent page; drawers/modals overlay the parent page and preserve context; pure navigation actions only mark the trigger and destination. Whether formal visual approval is required follows the project process; this skill does not add mandatory approval on its own.
Interface acceptance, business operation, and platform support are recorded separately. Target dimensions come from the project and are not inferred from historical examples. When paired visual acceptance is required, unify data, font, language, theme, scaling, state, and dimensions, and record specific tolerances.
6. Delivery and checks
A complete delivery always includes the seven Markdown documents and the machine index specified by the contract, without merging or deleting based on scale. Use thetemplate; for fields that do not apply, write a specific reason; register missing information as a blocker and do not pass off an empty template as completion. Formal implementation tasks reference the existing specification system; if new design details change requirements, first update the formal specification according to the project process and do not create two conflicting sources of truth.
Execute item by item thereview checklist. The structural check verifies unique IDs, existing links, mutual references and coverage among features/Surfaces/flows; the product review additionally checks that information is sufficient, operations are reasonable, and permissions and side effects are correct. The structural check cannot replace it.
Finally, explain the document entry points, actual coverage, key design decisions, unresolved items, executed verification, and evidence not yet run. Existing page counts/task counts must not be automatically converted into "the complete product has been designed/implemented."
Required for planned tasks
Derive design, implementation, and verification tasks from features and Surfaces, and formulate the plan according to the project's current authorization scope. For each item, write dependencies, phase, responsible role, inputs, outputs, acceptance, and verification method; map the unique locator in the original task source. In addition to the master table, provide task execution instructions according to the fixed working method, clarifying the first-screen problem, objects/navigation, business fields, parent page dependencies, allowed changes, action destinations, and state acceptance (simple tasks may be inline). Check that all features/Surfaces have tasks, dependencies are acyclic, and there are no tasks with no input/output or only vague tasks such as "improve the page." Completing only planning must not be checked off as implementation.