easysdd-explore
The first time you spend two hours investigating code for the same question, you should find the answer within five minutes the second time—provided you leave evidence-based records after the first exploration. easysdd-explore is designed to document a complete process of "Asking Questions → Reading Code → Reaching Conclusions" into searchable exploration documents.
Applicable Scenarios
- New team members join the repository and need to quickly understand module boundaries, call chains, and entry files
- Users raise a specific question but do not require immediate solutions / fixes
- Conduct evidence-based exploration before feature-design / issue-analyze / issue-fix
- Technical directions are still under discussion, requiring lightweight spike (exploration only, no final decisions)
This skill only focuses on evidence-based documentation of "what is observed". If the user's actual intent is something else (making decisions, providing solutions, fixing bugs), the root skill easysdd will route them to the corresponding sub-skill.
Refer to
easysdd/reference/shared-conventions.md
for shared paths and naming conventions. The output of this skill is written to
, with file names formatted as
YYYY-MM-DD-explore-{slug}.md
, and frontmatter tagged with
.
Three Types of Exploration Documents
Each exploration document belongs to one of the following three categories, marked in the
field of the frontmatter:
| Type | Applicable Scenarios |
|---|
| Investigate code around a specific problem and provide conclusions |
| Quickly organize the structure, boundaries, entry points, and dependencies of a module |
| Conduct lightweight technical exploration of multiple possible directions (no final decisions) |
Document Format
The frontmatter, body structure, section writing instructions, and examples of exploration documents have been split into
in the same directory. This skill only retains process constraints:
- Quick answers must appear before evidence—readers should see conclusions first when opening the document, then decide whether to read further for evidence
- Conclusions must be traceable to evidence; pure speculation is not allowed
- If evidence is insufficient, set to or
- When old explorations become outdated, mark the old document as and create a new version for the current state
Workflow Phases
Phase 1: Converge Exploration Questions
Ask the user at most two questions:
- "What is the single most important question you want to answer first?"
- "Which module / directory do you want to focus on?"
If the user's description is clear, proceed directly to Phase 1.5.
Phase 1.5: Check for Overlaps and Intent Routing (Mandatory)
Follow §6, Items 5 / 6 in
easysdd/reference/shared-conventions.md
:
- If the user mentions "update / review / a previous explore / this module was explored before" or explicitly points to an old explore document → directly follow the update or supersede path. The characteristic of explore is: when code changes render old conclusions invalid, mark the old document as and create a new one (supersede); when only supplementing evidence / tightening conclusions but core conclusions remain unchanged, follow the "update existing entry" path
- Otherwise, use the "Search Tools" below to search by keywords / modules. If a similar old explore document is found, read it first. If it can directly answer the question, inform the user: "There is an available explore document at {path}. Do you want to reuse it or conduct a new exploration?"
Update Path: Read the old document → supplement evidence according to Phase 2 → rewrite the quick answer section → write back to the original file and add
.
Phase 2: Evidence-Based Exploration
- Use Glob / Grep / Read to actually read code, do not rely on guesses
- Accumulate evidence while reading; simultaneously think about which conclusion each piece of evidence supports—do not record evidence that does not support any conclusion
- Aim for 3–8 key pieces of evidence, each marked with
- When involving multi-module collaboration, or for / types, prepare a Mermaid diagram and place it in the quick answer section drafted in Phase 3
- After forming preliminary conclusions, actively check: Can the existing evidence convince a skeptical person? If yes, stop; there is no need to expand the search scope further
Why "stop when enough"? Exploration is not exhaustive; it is about building an evidence chain until "readers can trust it". Expanding the scope further will only make the document longer without increasing its credibility.
Phase 3: Drafting and Confirmation
- Write the quick answer section first, then fill in key evidence—this order is crucial: having conclusions first forces you to check whether the evidence actually supports them, ensuring the effectiveness of each piece of evidence
- The AI drafts the complete explore document at once, and the user confirms after review
- Revise according to feedback before finalizing if there are changes
Phase 4: Archiving
- New Path: Write to , name the file
YYYY-MM-DD-explore-{slug}.md
- Update Path: Write back to the original file located in Phase 1.5, and add to the frontmatter
- Supersede Path: Follow §6, Item 5 in ; mark the old document as and add
Phase 5: Provide Next-Step Suggestions
After collecting all evidence, give a one-sentence prompt to the user about possible next steps (e.g., "Would you like to design a solution based on this explore document?"). Skip this if the user says "No"—routing is handled by the root skill.
Search Tools
See
easysdd/reference/tools.md
for complete syntax and examples. This section only lists typical queries specific to explore.
bash
# Filter by type
python easysdd/tools/search-yaml.py --dir easysdd/compound --filter doc_type=explore --filter type=module-overview --filter status=active
# Check for overlaps after archiving
python easysdd/tools/search-yaml.py --dir easysdd/compound --filter doc_type=explore --query "{keywords}" --json
Exit Conditions
Guardrails
Shared guardrails for archiving workflows (add-only, quality over quantity, do not write on behalf of users, discoverability, check for overlaps after archiving) can be found in §6 of
easysdd/reference/shared-conventions.md
. Anti-patterns specific to this skill:
- Providing conclusions without reading code
- Evidence only states "looks like" without marking File: Line Number
- Conclusions are written after evidence—the quick answer section must come before the key evidence section
- The evidence section is several times longer than the quick answer section—first streamline evidence and delete entries that do not support conclusions
- No Mermaid diagram for cross-module processes, only textual descriptions of multi-module collaboration
- Making decisions in advance—explore only records "what is observed" and does not make conclusions on "what should be done in the future"
- Providing solutions without an evidence chain—each conclusion must be traceable to specific File: Line Number
- Continuing to reference outdated historical explore documents without marking
- Reading or writing documents in the directory where is not —this skill only handles explore documents