cs-decide
The "intentional choices" made in a project — tech stack selections, architecture decisions, long-term constraints, and coding conventions — are particularly prone to being lost. They won't trigger errors, and no one will notice when they disappear, but the cost of their disappearance is tangible:
- 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
The responsibility of this workflow is to ensure that every important "finalized decision" has a complete archive: what it is, why it was made, what alternative solutions were considered, and what the consequences are.
See
codestable/reference/shared-conventions.md
for shared paths and naming conventions. The output of this skill is written to
, with the file named
YYYY-MM-DD-decision-{slug}.md
, and the frontmatter includes
.
Four Decision Categories
Each decision document belongs to one of the following four categories, marked in the
field of the frontmatter:
| Category | Applicable Scenarios | Examples |
|---|
| Selection of technologies/libraries/frameworks | "Use Vite instead of Webpack", "Use Pinia for state management" |
| System structure, module division, data flow direction | "Complete separation of front-end and back-end", "Event bus only used at the top level" |
| Hard constraints — things that are not allowed | "Do not introduce jQuery", "All API calls must go through the unified http module" |
| Soft conventions — things done uniformly | "Component naming uses PascalCase", "Side effects are concentrated in composables/" |
Each category serves a different purpose in actual queries:
- To check "what tools do we use" →
- To check "how the system is organized" →
- To check "why can't this be changed" →
- To check "what is the uniform practice" →
Document Format
The frontmatter, body template, and examples of decision documents have been split into
in the same directory. This skill only retains process constraints:
- only allows / / /
- only allows / /
- The "Alternative Solutions Considered" and "Related Documents" sections are optional; omit them if the user says "nothing"
Workflow Phases
Phase 1: Identify the Decision (Dialogue with User)
Confirm key information with one question at a time; do not present the user with a large form:
- "What is this decision about? (Tech stack selection / Architecture structure / Constraint / Convention)" → Determine the
- "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.
- If the user's description is not clear enough, ask "Why was this chosen instead of other options at that time?"
Phase 1.5: Check for Duplicates and Intent Diversion (Mandatory)
Execute according to Sections 5/6 of §6 in
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 + keywords. When a similar old decision is found, present the candidates to the user and let them choose: update / supersede / truly different topic
Simple Rule for Judging Update vs Supersede: If the conclusion changes → supersede; if the conclusion remains unchanged and only supplements are added → update. Ask the user if unsure.
Phase 2: Extract Key Points (One Question at a Time)
Ask in the following order; the user can say "nothing" at any time to skip:
- "What was the background or problem faced at that time?"
- "What is the conclusion of the decision?" (Skip if the user has already made it clear)
- "Why was this chosen? What is the most important reason?"
- "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")
- "What impact or constraints does this decision impose on subsequent work?"
Phase 3: Confirm Content (AI Drafts, User Reviews)
- 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.
Phase 4: Archive
- New path: Write the file to , named
YYYY-MM-DD-decision-{slug}.md
- Update path: Write back to the original file located in Phase 1.5, add to the frontmatter
- Supersede path: Process according to Section 5 of §6 in ; set for the old document and add the field (consistent with Guard Rule #2 of this skill)
- Report the complete file path after writing
Phase 5: Prompt for Related Workflow Updates
Check these two items after writing; prompt the user if applicable (do not modify the files without permission — both files are high-impact entry points):
- Whether the "Key Architecture Decisions" section of
codestable/architecture/DESIGN.md
- Whether this constraint should be added to the "Prohibited Items" or "Code Specifications" section of — usually applicable for or categories
Search Tool
See
codestable/reference/tools.md
for complete syntax and examples. This section only lists typical queries specific to decisions.
bash
# 列出所有当前有效的决策
python codestable/tools/search-yaml.py --dir codestable/compound --filter doc_type=decision --filter status=active
# 按类型 + 状态组合筛选
python codestable/tools/search-yaml.py --dir codestable/compound --filter doc_type=decision --filter category=constraint --filter status=active
# 归档后查重叠
python codestable/tools/search-yaml.py --dir codestable/compound --filter doc_type=decision --query "{关键词}" --json
Relationship with Project Architecture Documentation
is the architecture overview (high-level, cross-module, long-term stable); decision documents are complete archives of individual decisions (including reasons and alternative solutions). The "Key Architecture Decisions" section of DESIGN.md should link to relevant decision documents (the discoverability check in Phase 5 will prompt the user to update this).
Guard Rules
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:
- Only archive finalized decisions — do not archive proposed solutions under discussion; do not archive "maybe we should use X"
- status=superseded does not mean deletion — retain the original text of the superseded decision, add the field, and add a line at the top of the body: "[Superseded] See {new document slug}"
- 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)
- 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.
- 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.
- Only recognize its own doc_type — only read and write documents with ; do not perceive other documents with different in the directory.