cs-explore
Spending two hours investigating code for the same question the first time, you should find the answer within five minutes the second time — provided that evidence-based records were created after the first exploration. cs-explore is designed to document a complete process of "Ask Questions → Read Code → Draw Conclusions" into searchable exploration documents.
Applicable Scenarios
- New team members joining the repository 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 first (only exploration, no final decisions)
This skill only focuses on evidence-based documentation of "what was observed". If the user's actual intent is something else (making decisions, providing solutions, fixing bugs), ask the user to select the corresponding sub-skill based on the scenario, and do not take over the task without permission.
Refer to
codestable/reference/shared-conventions.md
for shared paths and naming conventions. The output of this skill is written to
, with the file name format
YYYY-MM-DD-explore-{slug}.md
, and the frontmatter includes
.
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 question and provide conclusions |
| Quickly sort out 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 are detailed in
in the same directory. This skill only retains process constraints:
- Quick answers must come before evidence — Readers should see the conclusion first when opening the document, then decide whether to read the evidence
- Conclusions must be traceable to evidence; pure speculation is not allowed
- When 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 top 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 Diversion (Mandatory)
Follow Section 6, Items 5 / 6 of
codestable/reference/shared-conventions.md
:
- If the user mentions "update / review / a previous explore / this module was explored before" or clearly 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); if only supplementing evidence / tightening conclusions without changing core conclusions, 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
to the frontmatter.
Phase 2: Evidence-Based Exploration
- Use Glob / Grep / Read to actually read code, do not rely on speculation
- 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? Stop once sufficient, do not expand the search scope unnecessarily
Why "stop once sufficient"? 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 the conclusion first forces you to check whether the evidence actually supports it, ensuring the validity of each piece of evidence
- AI drafts the complete explore document at once, and the user confirms after review
- Revise according to feedback before finalizing if there are modifications
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, add to the frontmatter
- Supersede Path: Follow Item 5 of Section 6 in ; mark the old document as and add
Phase 5: Provide Next-Step Suggestions
After collecting all evidence, give the user a one-sentence hint about possible next steps (e.g., "Do you want to design a solution based on this explore document?"). Skip this if the user says "No need" — let the user decide the next workflow.
Search Tools
See
codestable/reference/tools.md
for complete syntax and examples. This section only lists typical queries specific to explore.
bash
# Filter by type
python codestable/tools/search-yaml.py --dir codestable/compound --filter doc_type=explore --filter type=module-overview --filter status=active
# Check for overlaps after archiving
python codestable/tools/search-yaml.py --dir codestable/compound --filter doc_type=explore --query "{keywords}" --json
Exit Conditions
Guardrails
Shared guardrails for archiving workflows (add-only, quality over quantity, do not write for users, discoverability, check for overlaps after archiving) are in Section 6 of
codestable/reference/shared-conventions.md
. Anti-patterns specific to this skill:
- Providing conclusions without reading code
- Evidence only says "looks like" without marking File: Line Number
- Conclusions are placed 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 was observed", not conclusions on "what should be done in the future"
- Providing solutions without an evidence chain — every 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