• New team members (or yourself six months later) don't know the context of constraints, and waste time re-discussing issues that have already been decided
• 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 of the modification

See

codestable/reference/shared-conventions.md

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

codestable/compound/

, with the file named

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

, and the frontmatter includes

doc_type: decision

.

category

tech-stack

architecture

constraint

convention

• To check "what tools do we use" →

  tech-stack

• To check "how the system is organized" →

  architecture

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

  constraint

• To check "what is the uniform practice" →

  convention

reference.md

• category

  only allows

  tech-stack

  /

  architecture

  /

  constraint

  /

  convention

• status

  only allows

  active

  /

  superseded

  /

  deprecated

• The "Alternative Solutions Considered" and "Related Documents" sections are optional; omit them if the user says "nothing"

1. "What is this decision about? (Tech stack selection / Architecture structure / Constraint / Convention)" → Determine the

   category

2. "Has this decision been finalized, or is it still under discussion?" → This workflow only archives finalized decisions; do not archive those under discussion (advise the user to come back after the discussion is complete). The reason is that if a proposed solution under discussion is archived, someone who finds it later will think it has been finalized, which will be misleading.
3. If the user's description is not clear enough, ask "Why was this chosen instead of other options at that time?"

codestable/reference/shared-conventions.md

• If the user's words include "modify / update / overturn / a certain decision / a certain selection" or clearly refer to an old decision → Directly follow the update or supersede path. A characteristic of decision documents is: Almost any change to the conclusion itself requires superseding (the old conclusion must be retained and cannot be overwritten in place); only follow the "update existing entry" path when supplementing background / alternative solutions / impact descriptions.
• Otherwise, use the "Search Tool" below to search by

  category

  + keywords. When a similar old decision is found, 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 was this chosen? What is the most important reason?"
4. "Were there any other solutions considered? Why weren't they chosen?" (Encourage writing this down, even if it's just intuition — what future team members most want to know is "why X wasn't chosen")
5. "What impact or constraints does this decision impose on subsequent work?"

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

• New path: Write the file to

  codestable/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 5 of §6 in

  shared-conventions.md

  ; set

  status=superseded

  for the old document and add the

  superseded-by

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

1. Whether the "Key Architecture Decisions" section of

   codestable/architecture/DESIGN.md

   should reference this decision — usually applicable for

   architecture

   or

   tech-stack

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

   AGENTS.md

   — usually applicable for

   constraint

   or

   convention

   categories

See

codestable/reference/tools.md

for complete syntax and examples. This section only lists typical queries specific to decisions.

undefined

See Section 6 of

codestable/reference/shared-conventions.md

for shared guard rules for archiving workflows (add only, do not delete; quality over quantity; do not write on behalf of users; discoverability; check for duplicates after archiving). Rules specific to or refined for this skill:

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

   superseded-by

   field, and add a line at the top of the body: "[Superseded] See {new document slug}"
3. Do not write reasons on behalf of the user — if the user cannot provide a reason, write "No systematic evaluation was conducted"; do not let AI fabricate seemingly reasonable reasons (fabricated reasons will become historical "facts" that mislead future team members)
4. Do not actively modify AGENTS.md and DESIGN.md — only prompt in Phase 5; let the user decide whether to add content. The content of these two files must be finalized by the project owner.
5. Cross-skill consistency — if the description of a prohibited item differs between a decision document and AGENTS.md, the decision document shall be the detailed version, and AGENTS.md shall be 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 documents with different

   doc_type

   in the

   compound/

   directory.