easysdd
In AI-aided development, several scenarios recur frequently — adding new features, fixing bugs, encountering experiences worth documenting, making technical selections, exploring code of new modules, and integrating new repositories. If each scenario is handled from scratch every time, typical issues will arise: the terminology AI uses for features conflicts with legacy code, no one remembers how a bug was diagnosed after it's fixed, and the pitfalls stepped on last week are repeated the next week.
easysdd assigns a set of sub-skills to each of these scenarios, with outputs stored in a unified directory structure with standardized YAML frontmatter, allowing cross-retrieval and reference between them.
Skill Components
Execution — Moving from a vague idea to a launched feature, or from an error report to a fixed bug:
- — New features, following brainstorm → design → implement → acceptance
- — Bug fixing, following report → analyze → fix
Neither directly lets AI write code; instead, they first produce a spec (feature plan / problem analysis), which is reviewed by users before implementation, with code and docs delivered together. This prevents three common AI pitfalls: terminology conflicts, scope creep, and lack of documentation after fixes.
Knowledge Preservation — Saving knowledge generated during execution for reuse in similar future scenarios:
- — Recap "We encountered pitfall Y when doing X"
- — Prescriptive guide "Do X this way in the future"
- — Official rule "All projects must follow X from now on"
- — Archive "Investigated issue X, here's what the code shows"
Auxiliary Tools — Peripheral tools supporting the above two categories:
- — Integrate new repositories into the easysdd directory structure
- — Draft or update architecture documents under
easysdd-architecture-check
- — Developer guides / user guides for external readers
- — Generate reference documentation for each public API of a library
Scenario Routing
If there is no
directory in the repository, use
to set up the framework first.
| Scenario | Sub-skill |
|---|
| New feature / new capability | |
| BUG / exception / documentation error | |
| Code exploration, research & questions | |
| Supplement / update architecture documents | |
| Check design consistency | easysdd-architecture-check
|
| Technical selection / constraints / specifications | |
| Pitfall recap, experience summary | |
| Reusable programming patterns, library usage | |
| Developer guide / user guide | |
| Library API reference | |
Complete operation manuals, exit conditions, and relationships with other workflows are covered in each sub-skill.
Distinction Between Four Preservation Sub-skills
learning / trick / decision / explore are all archive document types, differing in the nature of recorded content:
- Recap that Y was discovered when doing X — (produces )
- Prescriptive guide for doing X in the future — (produces )
- Official rule that all projects must follow — (produces )
- Archive of evidence from investigating a problem — (produces )
All four share the
directory, distinguished by the
field in frontmatter and the type segment in filenames (
YYYY-MM-DD-{doc_type}-{slug}.md
). Each sub-skill only recognizes its own
and does not read/write outputs of others —
Judgments like "What's the difference between A and B" are handled in this section and not repeated in sub-skills.
Stages of feature and issue Cannot Be Skipped
feature follows brainstorm (optional) → design → implement → acceptance, while issue follows report → analyze → fix. Each stage has exit conditions; the next stage cannot start until the previous one is satisfied.
The most common AI pitfall is generating hundreds of lines of code at once before review — making it hard to stop once problems are found. Manual checkpoints between stages are designed to catch issues earlier. Specific inspection items for each checkpoint are covered in the corresponding sub-skill.
Two exceptions: For issues where the root cause is obvious, use the fast track to skip analyze and go directly to fix; for small-scope features, use
easysdd-feature-fastforward
to enter implementation immediately after writing the spec.
Further References
Shared reference documents are copied from the skill package's
easysdd-onboarding/reference/
to the project's
directory once via
— each sub-skill reads them using project relative paths at runtime, which is the only accessible sharing method under the premise of independent skill installation.
easysdd/reference/shared-conventions.md
easysdd/reference/tools.md
easysdd/reference/maintainer-notes.md
The authoritative definition of the directory structure (features/, issues/, compound/, architecture/, tools/, reference/) is in
. To modify the directory, first update the template in
easysdd-onboarding/reference/shared-conventions.md
— new projects will include the updated version during onboarding.
The four preservation sub-skills (learning / tricks / decisions / explore) share a single
directory, distinguished by the frontmatter
and type segment in filenames, instead of having separate directories.
Related
- — Project-wide code specifications and known pitfalls
easysdd/architecture/DESIGN.md