• New team members (or yourself six months later) don't know the context of constraints, and waste time re-discussing "already decided issues"
• AI provides "reasonable but conflicting with project conventions" solutions without decision context
• When constraints need to be modified, the original reasons cannot be found, making it impossible to assess the scope of impact

See

easysdd/reference/shared-conventions.md

for shared paths and naming conventions. The output of this skill is written to

easysdd/compound/

, with files named

YYYY-MM-DD-decision-{slug}.md

and frontmatter containing

doc_type: decision

.

category

tech-stack

architecture

constraint

convention

• To check "which tools do we use" →

  tech-stack

• To check "how is the system organized" →

  architecture

• To check "why can't this be changed" →

  constraint

• To check "what is the unified practice" →

  convention

reference.md

• category

  only allows

  tech-stack

  /

  architecture

  /

  constraint

  /

  convention

• status

  only allows

  active

  /

  superseded

  /

  deprecated

• The "considered alternatives" and "related documents" sections are optional; omit them if the user says "nothing"

1. "What is this decision about? (Technology selection / Architecture structure / Constraint / Convention)" → determine

   category

2. "Has this decision been finalized, or is it still under discussion?" → This workflow only archives finalized decisions, do not archive under-discussion solutions (advise the user to come back after discussion). The reason is that if under-discussion solutions are archived, someone who finds them later will think they have been finalized, which is misleading
3. If the user's description is not clear enough, ask "Why did you choose this instead of others at that time?"

easysdd/reference/shared-conventions.md

• If the user's words contain "modify/update/overturn/a certain decision/a certain selection" or clearly point to an old decision → directly take the update or supersede path. A characteristic of decision documents: changes to the conclusion itself almost always require supersede (the old conclusion must be retained, cannot be overwritten in place); only take the "update existing entry" path when supplementing background/alternatives/impact descriptions
• Otherwise, use the "search tool" below to search by

  category

  + keywords. When a similar old decision is hit, present the candidates to the user and let them choose: update / supersede / truly different topic

1. "What was the background or problem faced at that time?"
2. "What is the conclusion of the decision?" (Skip if the user has already made it clear)
3. "Why did you choose this? What is the most important reason?"
4. "Were there any other alternatives considered? Why weren't they chosen?" (Encourage writing, even if it's just intuition — what future generations most want to know is "why not choose X")
5. "What impact or constraints does this decision have on subsequent work?"

• AI drafts a complete document (including YAML frontmatter + all body sections) based on the dialogue
• Show the full version to the user for review at once, do not show section by section and ask section by section — the user can only judge whether the logic between sections is consistent when they get the full version
• Write to the file after user confirmation; adjust according to the user's comments if there are modifications

• New path: Write the file to

  easysdd/compound/

  , named

  YYYY-MM-DD-decision-{slug}.md

  , with

  doc_type: decision

  at the top of the frontmatter (see

  reference.md

  )
• Update path: Write back to the original file located in Phase 1.5, add

  updated: YYYY-MM-DD

  to the frontmatter
• Supersede path: Process according to Section 6, Item 5 of

  shared-conventions.md

  ; set the old document's

  status=superseded

  and add the

  superseded-by

  field (consistent with this skill's Guard Rule #2)
• Report the complete file path after writing

1. Whether the "Key Architecture Decisions" section of

   easysdd/architecture/DESIGN.md

   should reference this decision — usually applicable for

   architecture

   or

   tech-stack

   types
2. Whether this constraint should be added to the "Prohibited Items" or "Code Specifications" section of

   AGENTS.md

   — usually applicable for

   constraint

   or

   convention

   types

Complete syntax and examples can be found in

easysdd/reference/tools.md

. This section only lists typical queries specific to decisions.

undefined

Shared guard rules for archiving workflows (add-only, quality over quantity, do not write for users, discoverability, check for overlaps after archiving) can be found in Section 6 of

easysdd/reference/shared-conventions.md

. Rules specific to or refined for this skill:

1. Only archive finalized decisions — do not archive under-discussion solutions; do not archive "maybe we should use X"
2. status=superseded does not equal deletion — retained the original text of superseded decisions, add the

   superseded-by

   field, and add a line "[Superseded] See {new document slug}" at the top of the body
3. Do not make up reasons for users — if the user cannot state the reason, write "No systematic evaluation was done", do not let AI fabricate seemingly reasonable reasons (fabricated reasons will become historical "facts" and mislead future generations)
4. Do not actively modify AGENTS.md and DESIGN.md — only prompt in Phase 5, let the user decide whether to add. The content of these two files must be finalized by the project owner
5. Cross-skill consistency — when a decision document and the prohibited items in AGENTS.md have different descriptions, take the decision document as the detailed version and AGENTS.md as the summary version; the two should be linked and not contradictory
6. Only recognize its own doc_type — only read and write documents with

   doc_type: decision

   , do not perceive other

   doc_type

   documents in the

   compound/

   directory