SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillscs-decide

cs-decide

Design & creation

View repository

Updated 10-15 20:21

About this skill

cs-decide

Required reading on startup

Before making any judgment or taking any action, first read .codestable/attention.md; if missing, treat the skeleton as incomplete, prompt to fill it in first or run cs-onboard, and do not fall back to an external AI entry file.

The "choices deliberately made" in a project—technology choices / architectural decisions / long-term constraints / coding conventions—are especially easy to lose. They won't trigger an error, no one will notice they've disappeared, but the cost of the disappearance is very concrete:

  • Newcomers (or your future self six months later) don't know the reasoning behind a constraint and waste time re-discussing "questions that have already been decided"
  • AI lacks the decision context and gives solutions that are "reasonable but conflict with project conventions"
  • When a constraint needs to be modified, the original rationale can't be found, making it impossible to assess the impact of the change

This workflow gives every important "already decided" item a complete archive:What it is, why, what alternatives were considered, what the consequences are。

For shared paths and naming conventions see .codestable/reference/shared-conventions.md. Artifacts are written to .codestable/compound/, named YYYY-MM-DD-decision-{slug}.md, with frontmatter containing doc_type: decision。

Four decision types

Each entry belongs to one of the four categories (marked by the category field in frontmatter):

Type Applicable situation Example
tech-stack Choice of technology / library / framework "Use Vite instead of Webpack", "Use Pinia for state management"
architecture System structure, module division, data flow direction "Complete separation of frontend and backend", "The event bus is only used at the top level"
constraint Hard constraint—certain thingsare not allowedto be done "Do not introduce jQuery", "All API calls must go through the unified http module"
convention Soft convention—certain thingsare uniformly done this way "Name components with PascalCase", "Concentrate side effects in composables/"

Each has its use when querying: looking up "what tool to use" → tech-stack; "how the system is organized" → architecture; "why can't this be changed" → constraint; "what is the unified approach" → convention.

Document format

For frontmatter / body templates / examples see the same directory reference.md. The process constraints of this skill:

  • category only allows tech-stack / architecture / constraint / convention
  • status only allows active / superseded / deprecated
  • "Alternatives considered" and "Related documents" are optional sections; if the user says "nothing", omit them

Workflow phases

Phase 1: Identify the decision

Useone questionto confirm key information, don't give the user a big table:

  1. "What is this decision about? (technology choice / architecture / constraint / convention)" → determine category
  2. "Is it finalized or still under discussion?" → This workflow only archives what has been finalized, what's under discussion is not archived (suggest coming back after the discussion is done). Rationale: if a plan under discussion is archived, the next person who looks it up will think it's already decided, which is misleading instead
  3. If the description is unclear, ask "Why was this chosen at the time rather than something else?"

Phase 1.5: Check for overlaps and route by intent (mandatory)

Follow shared-conventions.md §6 clauses 5/6:

  • If the user's words contain "change / update / overturn / a certain decision / a certain choice" or clearly point to an old decision → go directly toupdate or supersede. Decision document characteristics:A change to the conclusion itself almost always requires supersede(the old conclusion must be kept on record and cannot be overwritten in place); when only supplementing background / alternatives / impact description, go with "update the existing entry"
  • Otherwise use the "search tool" below to search once by category + keyword, and when a similar old decision is found, present the candidates to the user

update vs supersede: the conclusion changed → supersede; the conclusion did not change and it is only a supplement → update. If unsure, ask the user.

Phase 2: Extract key points (one question at a time)

The user can say "nothing" at any time to skip:

  1. "What background or problem were you facing at the time?"
  2. "What is the conclusion of the decision?" (skip if already clearly stated)
  3. "Why choose this one? What is the most important reason?"
  4. "Did you consider other options? Why were they not chosen?" (encourage writing even if it is just intuition—what later people most want to know is "why not choose X")
  5. "What impact or constraints does this decision have on subsequent work?"

Phase 3: Draft + user review

The AI drafts the complete document based on the conversation (YAML frontmatter + all body sections). Show it to the user for review all at once,do not show it section by section and ask section by section—only with the complete version can the user judge whether the logic between sections is self-consistent.

Phase 4: Archive

  • New: write to .codestable/compound/YYYY-MM-DD-decision-{slug}.md, with doc_type: decision
  • Update: write back to the original file located in Phase 1.5, and add to the frontmatter updated: YYYY-MM-DD
  • supersede: handle according to shared-conventions.md §6 clause 5; the old document status: superseded + superseded-by

Phase 5: Prompt for related workflow updates

After writing, check the two items and prompt the user if present (do not change files on your own initiative）：

  1. architecture/ARCHITECTURE.md whether the "Key Architecture Decisions" section should reference—architecture or tech-stack usually should
  2. .codestable/attention.md whether a one-sentence must-read summary at startup should be appended—constraint or convention usually should

Search tool

For the complete syntax, see .codestable/reference/tools.md。

# 列出所有当前有效的决策

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

Guard rules

The shared guard rules for archival workflows (append only / do not overdo it / do not write on the user's behalf / discoverability / check for overlaps after archiving) are in shared-conventions.md Section 6. Specific to this skill:

  1. Only archive decisions that have already been finalized—options still under discussion are not archived
  2. status=superseded does not equal deletion—the superseded document keeps the original text + superseded-by + at the top of the body **[已取代]** 见 {新文档 slug}
  3. Do not write reasons on the user's behalf—if the user cannot say, write "no systematic evaluation was done"; do not fabricate (fabricated reasons will become historical "facts" and mislead later people)
  4. Do not proactively modify attention.md and ARCHITECTURE.md—Phase 5 only prompts; the user decides; appending to attention.md is left to cs-note
  5. Cross-skill consistency—when decision and attention.md describe things differently, treat decision as the detailed version and attention.md as the summary version; the two should link to each other and not contradict each other
  6. Only recognize its own doc_type—only read and write doc_type: decision