easysdd-tricks
easysdd-tricks is a problem-oriented prescriptive reference library that answers one question: What is the verified correct way to do X? No trigger event is required; you can directly write whenever you find a pattern or usage worth documenting.
Typical content:
- Standard implementation of a design pattern in this project
- Core API usage + known pitfalls of a specific library/framework
- Command recipes for certain operations (debugging, deployment, data processing...)
See
easysdd/reference/shared-conventions.md
for shared paths and naming conventions. The output of this skill is written to
, with files named
YYYY-MM-DD-trick-{slug}.md
and a frontmatter field
.
Three Document Types
Each trick document belongs to one of the following three categories, marked in the
field of the frontmatter:
| Type | Applicable Scenarios | Examples |
|---|
| Design patterns, architectural patterns, programming idioms | "Use Repository pattern to isolate data access layer", "Use Builder pattern to construct complex configuration objects" |
| Usage, configuration methods, common pitfalls of a specific library/framework | "Correct implementation of Prisma transactions", "Error handling for Pinia store actions" |
| Specific operation skills, tool usage, command recipes | "Extract nested fields from JSON using jq", "Locate bug-introducing commits with git bisect" |
Each type serves different purposes during queries:
- For questions like "How should I organize my code" →
- For questions like "How to use a certain API of this library/framework" →
- For questions like "How to perform this type of operation" →
If you're unsure, choose the closest one; the
field doesn't affect search usability.
Document Format
The frontmatter, body template, and long examples of trick documents have been moved to
in the same directory. This skill only retains judgment and process rules:
- only allows / /
- Prioritize using real code or commands from the project for examples
- Sections like "When not to use", "Known pitfalls", and "Related documents" are optional; omit them if the user says "Nothing"
Workflow Phases
Phase 1: Identify Type (Dialogue with User)
Confirm core information with at most two questions:
- "Is this about patterns/structures, usage of a specific library/framework, or operation skills/commands?" → Determine
- "In one sentence: When would this be used?" → Determine
Skip directly to Phase 1.5 if the user's description is clear enough.
Phase 1.5: Check for Duplicates and Intent Diversion (Mandatory)
Execute according to Section 6, Items 5/6 of
easysdd/reference/shared-conventions.md
:
- If the user's words include "modify/update/revise/supplement/a certain trick" or explicitly point to an old document → Follow the update existing entry path directly, do not enter the creation process; search only to confirm which entry to locate
- Otherwise, use the parameter in the "Search Tools" below to search for the . If semantically similar old documents are found, present the candidates to the user and let them choose: update / supersede / confirm it's a different topic before proceeding to Phase 2
Process for updating existing entries: Directly read the old document → Align with the user on which sections to modify → Skip the complete code investigation in Phase 2 (but re-read the code related to the modified sections to confirm it hasn't become invalid) → Draft a diff for user review → Write back to the original file and add
.
Phase 2: Code Investigation (Mandatory, Cannot Be Skipped)
Techniques are embodied through code — the fact that users don't attach code doesn't mean you don't need to look at code. AI must actively investigate the code repository to find the actual implementation of the technique.
Why is this mandatory? "Techniques" written without checking code will remain at an abstract level. Next time someone looks for code according to this technique, they won't find corresponding real examples, which will instead undermine their confidence.
-
Search the code repository based on topic and type:
- Grep for keywords (function names, class names, library imports, pattern features)
- Search related files (by file name, directory structure, import path)
- Use semantic search for supplement if necessary
-
Read key files:
- Locate the code position where the technique is actually used or implemented, and read the context
- For type: Find the library's import statements and call sites
- For type: Find structural code of the pattern (interface definitions, class inheritance, composition relationships)
- For type: Find scripts or configurations corresponding to the operation steps
-
Output:
- Record the found file paths and key code snippets as the factual basis for subsequent drafting
- If no relevant code is found in the code repository (pure experiential techniques, external tool usages), state "No in-project code examples available for this technique" during Phase 3 drafting
Additional case handling:
- If the user attaches files → Still search the code repository to confirm if there are other usage points or related code
- If search results are empty → You can proceed (some techniques are indeed "for future use"), but must note this in the document
- If the found code contradicts the user's description → Proactively confirm with the user, don't proceed blindly
Phase 3: Refine Key Points (One Question at a Time)
Ask in the following order; the user can say "Nothing" to skip at any time. Combine the code found in Phase 2 to ask questions and supplement — don't ask about things the user can already see in the code:
- "What is the standard practice?" (or "What is the core API / steps?") → If the implementation is already found through code investigation, directly present your understanding for user confirmation
- "Why does this work? Is there any underlying principle?"
- "Are there any counterexamples — when shouldn't this be used?" (Optional)
- "Have you encountered any pitfalls or things to note?" (Optional, focus on this for type)
- "Are there any code snippets or command examples?" (Skip this question if actual code was found in Phase 2, directly use the real code as the basis for examples)
If the user says "Nothing" or "Skip" to a question, skip it. It's better to omit sections than fill them with empty words.
Phase 4: Confirm Content (AI Drafts, User Reviews)
- AI drafts the complete document (including YAML frontmatter + all body sections) based on the dialogue + code investigation results from Phase 2
- Prioritize using real project code found in Phase 2 for example code (can be simplified), don't write code out of thin air
- Present the complete draft to the user for review at once, don't show section by section and ask for confirmation
- Write to the file after user confirmation; adjust according to user's feedback if there are modifications
Phase 5: Archive
- Creation path: Write the file to , name it
YYYY-MM-DD-trick-{slug}.md
- Update path: Write back to the original file located in Phase 1.5, add to the frontmatter
- Supersede path: Handle the old and new files according to Section 6, Item 5 of
- Report the complete file path after writing
Phase 6: Discoverability Check
After writing, check if there are instructions in
or
guiding AI to access the
archive directory.
If not, prompt the user whether to add a line — don't modify the file without permission, only prompt and let the user decide.
Search Tools
See
easysdd/reference/tools.md
for complete syntax and examples. This section only lists typical queries specific to tricks.
bash
# Filter by type + framework
python easysdd/tools/search-yaml.py --dir easysdd/compound --filter doc_type=trick --filter type=library --filter framework~={library-name}
# Browse by tech stack
python easysdd/tools/search-yaml.py --dir easysdd/compound --filter doc_type=trick --filter language=typescript --filter status=active
# Check for duplicates after archiving
python easysdd/tools/search-yaml.py --dir easysdd/compound --filter doc_type=trick --query "{keywords}" --json
Guard Rules
Shared guard rules for archiving workflows (add-only, quality over quantity, don't write for users, discoverability, check duplicates after archiving) are in Section 6 of
easysdd/reference/shared-conventions.md
. Rules specific to this skill or refined rules:
- Only archive verified practices — "Maybe this should be done" is not archived; document content must be confirmed effective by users or AI
- Must investigate the code repository — The fact that users don't attach code doesn't mean you don't need to look at it; Phase 2 code investigation cannot be skipped. Prioritize using real project code for examples, don't write code out of thin air
- Don't write principles for users — If the user can't explain "why it works", write "Principle to be supplemented", don't make up plausible explanations with AI
- Examples take precedence over descriptions — Use code to explain things whenever possible, don't rely solely on text descriptions
- Only recognize its own doc_type — Only read documents with , don't perceive other documents in the directory