cs-explore

cs-explore

Required reading before starting

Before making any judgment or taking any action, first read .codestable/attention.md; if missing, treat the skeleton as incomplete, prompt to fill it in first or run cs-onboard, and do not fall back to an external AI entry file.

The first time you spend two hours looking through code for the same question, the second time you should find the answer within five minutes—provided the first time left behind an evidence-based record. cs-explore distills "ask a question → read the code → reach a conclusion" into a searchable exploration document.

Applicable scenarios

A newcomer quickly understanding a module's boundaries / call chain / entry points
The user raises a specific question but for now does not require directly producing a solution / fix
Before feature-design / issue-analyze / issue-fix, first add a round of evidence-based exploration
The technical direction is still under discussion and a lightweight spike is needed (explore only, no decision)

This skill is only responsible for evidence-based recording of "what was seen". If the user's intent is something else (deciding / prescribing / fixing a bug), let the user choose the corresponding sub-skill according to the scenario.

For shared paths and naming conventions, see .codestable/reference/shared-conventions.md. Artifacts are written to .codestable/compound/, named YYYY-MM-DD-explore-{slug}.md, with frontmatter containing doc_type: explore。

Three exploration types

The frontmatter's type field:

Type	Applicable situation
`question`	Investigate the code around a specific question and give a conclusion
`module-overview`	Quickly sort out a module's structure / boundaries / entry points / dependencies
`spike`	Do lightweight technical investigation of multiple possible directions (without making a final decision)

Document format

For frontmatter / body structure / explanations and examples of how to write each section, see the same directory reference.md. Process constraints:

The quick answer must appear before the evidence—the reader should see the conclusion first when opening it, then decide whether to read further into the evidence
Conclusions must be traceable to evidence; pure guesswork is not allowed
When evidence is insufficient, confidence must be downgraded to medium or low
Old exploration is outdated: mark the old document as outdated, and add the current version

Workflow phases

Phase 1: Converge on the exploration question

At most two questions:

"What is the one question you most want answered first?"
"Which module / directory do you want to focus on?"

If the user's description is already clear, go directly to Phase 1.5.

Phase 1.5: Check for overlap and triage intent (mandatory)

Execute according to shared-conventions.md §6 items 5/6:

If it contains "update / recheck / a certain explore / this module was explored before" or points to an old explore → go toupdate or supersede. explore special case:when the code has changed and the old conclusion is invalid, mark the old document as status: outdated + create a new one (supersede); when only adding evidence / tightening the conclusion but the core conclusion is unchanged, go to "update existing"
Otherwise use the search tool to search once by keyword / module; when a similar old explore is found, read it first, and if it can answer directly, tell the user "there is already one at {path}; reuse it or explore again?"

Update path: Read the old document → supplement evidence per Phase 2 → rewrite the quick-answer section → write back to the original file + updated: YYYY-MM-DD。

Phase 2: Evidence-based exploration

Use Glob / Grep / Read to actually read the codedon't rely on guessing
Accumulate evidence while reading;simultaneously think about which conclusion each piece of evidence supports— evidence that supports no conclusion is not recorded
3-8 key pieces of evidence, each annotated with 文件:行号
Multi-module collaboration or module-overview / spike type → prepare a Mermaid diagram to place in the quick-answer section
After forming a preliminary conclusion, proactively check: can the existing evidence convince a skeptical person? If enough, stop—no need to expand the search

Why "stop when enough": exploration is not exhaustive enumeration, it is building a chain of evidence until "the reader can believe it". Continuing to expand only makes the document longer, not more credible.

Phase 3: Drafting and confirmation

Write the quick-answer section first, then backfill the key evidence— this order matters: having the conclusion first and then looking back to see whether the evidence really supports it forces you to check the actual strength of each piece of evidence
AI drafts the complete document in one pass, the user reviews and confirms
If there are changes, revise per feedback before writing to disk

Phase 4: Archiving

New: write to .codestable/compound/YYYY-MM-DD-explore-{slug}.md, frontmatter includes doc_type: explore
Update: write back to the original file located in Phase 1.5 + updated: YYYY-MM-DD
supersede: per shared-conventions.md §6 item 5; old document status: outdated + superseded-by

Phase 5: Give next-step suggestions

Once the evidence is complete, prompt the next-step direction in one sentence ("Do you want to design a solution based on this explore"). If the user says "no need", skip it—the next step is decided by the user.

Search tools

For full syntax see .codestable/reference/tools.md。

# 按类型筛选

python .codestable/tools/search-yaml.py --dir .codestable/compound --filter doc_type=explore --filter type=module-overview --filter status=active

# 归档后查重叠

python .codestable/tools/search-yaml.py --dir .codestable/compound --filter doc_type=explore --query "{关键词}" --json

Exit conditions

The exploration question and scope are clearly defined
The quick-answer section gives the core conclusion (conclusion first)
3-8 key pieces of evidence, each marked with file:line and stating which conclusion it supports
For multi-module or module-overview / spike types, the quick-answer section has a Mermaid diagram
The document has been archived to compound/
Follow-up suggestions have been given

Guard rules

For shared archiving rules see shared-conventions.md Section 6. Anti-patterns specific to this skill:

Giving conclusions without reading the code
Evidence only says "looks like" without writing file:line
Conclusion written after the evidence—the quick-answer section must come before the key-evidence section
The evidence section is several times longer than the quick-answer section—trim the evidence, delete what doesn't support the conclusion
Cross-module flows have no Mermaid diagram, relying only on text description
Deciding prematurely—explore only records "what was seen", not "what should be done later"
Giving prescriptions directly without a chain of evidence—every conclusion must trace back to file:line
Historical explore has expired but is still referenced, without doing status annotation
Reading/writing documents that are not doc_type=explore —this skill is only responsible for explore