easysdd-decisions

Original：🇨🇳 Chinese

Translated

Document finalized technology selections, architecture decisions, long-term constraints, and coding conventions in the project into searchable permanent documents. No one will remember why X was chosen six months later, but with decision documents, at least the background can be understood before making changes next time. Four types: tech-stack (which tools/libraries/frameworks to use), architecture (how the system is organized), constraint (what is not allowed), convention (what is uniformly done). Trigger scenarios: Proactively push when important choices are made after feature-design or issue-analyze, or when the user says "record decision", "archive technology selection", "ADR", "record this constraint", "write down the convention". Only archive finalized decisions; do not archive under-discussion solutions.

3installs

Sourceliuzhengdongfortest/easysdd

Added on2026-04-20

NPX Install

npx skill4agent add liuzhengdongfortest/easysdd easysdd-decisions

SKILL.md Content (Chinese)

View Translation Comparison →

easysdd-decisions

"Intentional choices" in projects — technology selections, architecture decisions, long-term constraints, coding conventions — are extremely easy to lose. They won't trigger errors, no one will notice their disappearance, but the cost of their loss is concrete:

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

The responsibility of this workflow is to ensure every important "finalized decision" has a complete archive: what it is, why it was made, what alternatives were considered, and what the consequences are.

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
.

Four Decision Types

Each decision document belongs to one of the following four categories, marked in the

category

field of the frontmatter:

Type	Applicable Scenarios	Examples
`tech-stack`	Selection of technologies/libraries/frameworks	"Use Vite instead of Webpack", "Use Pinia for state management"
`architecture`	System structure, module division, data flow direction	"Complete separation of frontend and backend", "Event bus only used at the top level"
`constraint`	Hard constraints — certain things are not allowed	"Do not introduce jQuery", "All API calls must go through the unified http module"
`convention`	Soft conventions — certain things are uniformly done	"Component naming uses PascalCase", "Side effects are concentrated in composables/"

Each type serves a purpose in actual queries:

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
```

Document Format

The frontmatter, body template and examples of decision documents have been split into

reference.md

in the same directory. This skill only retains workflow constraints:

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"

Workflow Phases

Phase 1: Identify Decision (Dialogue with User)

Confirm key information with one question at a time, don't give the user a big form:

"What is this decision about? (Technology selection / Architecture structure / Constraint / Convention)" → determine
```
category
```
"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
If the user's description is not clear enough, ask "Why did you choose this instead of others at that time?"

Phase 1.5: Check for Overlaps and Intent Diversion (Mandatory)

Execute according to Section 6, Items 5/6 of

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

Simple rule for judging update vs supersede: If the conclusion changes → supersede; if the conclusion remains unchanged only with supplements → update. Ask the user if unsure.

Phase 2: Refine Key Points (One Question at a Time)

Ask in the following order; the user can say "nothing" to skip at any time:

"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 did you choose this? What is the most important reason?"
"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")
"What impact or constraints does this decision have on subsequent work?"

Phase 3: Confirm Content (AI Drafts, User Reviews)

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

Phase 4: Archive

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

Phase 5: Related Workflow Update Prompt

Check these two items after writing, and prompt the user if applicable (do not modify files without permission — these two files are high-impact entry points):

Whether the "Key Architecture Decisions" section of
```
easysdd/architecture/DESIGN.md
```
should reference this decision — usually applicable for
```
architecture
```
or
```
tech-stack
```
types
Whether this constraint should be added to the "Prohibited Items" or "Code Specifications" section of
```
AGENTS.md
```
— usually applicable for
```
constraint
```
or
```
convention
```
types

Search Tool

Complete syntax and examples can be found in
easysdd/reference/tools.md
. This section only lists typical queries specific to decisions.

bash

# List all currently active decisions
python easysdd/tools/search-yaml.py --dir easysdd/compound --filter doc_type=decision --filter status=active

# Filter by type + status combination
python easysdd/tools/search-yaml.py --dir easysdd/compound --filter doc_type=decision --filter category=constraint --filter status=active

# Check for overlaps after archiving
python easysdd/tools/search-yaml.py --dir easysdd/compound --filter doc_type=decision --query "{keywords}" --json

Relationship with Project Architecture Documentation

architecture/DESIGN.md

is an architecture overview (high-level, cross-module, long-term stable); decision documents are complete archives of individual decisions (including reasons and alternatives). 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).

Guard Rules

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:

Only archive finalized decisions — do not archive under-discussion solutions; do not archive "maybe we should use X"
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
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)
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
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
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

easysdd-decisions

NPX Install

Tags

SKILL.md Content (Chinese)

easysdd-decisions

Four Decision Types

Document Format

Workflow Phases

Phase 1: Identify Decision (Dialogue with User)

Phase 1.5: Check for Overlaps and Intent Diversion (Mandatory)

Phase 2: Refine Key Points (One Question at a Time)

Phase 3: Confirm Content (AI Drafts, User Reviews)

Phase 4: Archive

Phase 5: Related Workflow Update Prompt

Search Tool

Relationship with Project Architecture Documentation

Guard Rules