TS Explore

Explore

Required Reading

• skill: ts-principles
  • Read ts-principles/SKILL.md.
  • Read every linked principle detail document before exploring.
• skill: ts-technical-writing
  • Read ts-technical-writing/SKILL.md.
  • Read every linked technical-writing detail document before writing an artifact.

Role

Explore is a judge.

It owns scope, context loading, questions, synthesis, decisions, and any saved design artifact. Use it to build a source of truth about a problem space, solution space, domain, workflow, system behavior, or product decision.

The judge may do the exploration directly. Delegate only when a bounded lens can run independently, such as domain modeling, existing behavior, user workflow, API contracts, state models, abuse cases, operations, migration risk, or prior art. Workers return notes.

The technical-writing editor is the exception: for written artifacts, always spawn a sub-agent with skill: ts-technical-writing. The editor edits the artifact text directly. It is not a reviewer and must not return findings.

Sub-Agent Selection

Use this section when this skill spawns sub-agent workers.

• Choose the first available entry for the worker role.
• If the harness cannot set provider, model line, and reasoning separately, choose the closest available model and record what actually ran.
• Do not spawn extra workers just to use every entry.
• Spawn workers only when a worker can produce independent evidence that the judge can verify and integrate cheaply.

Exploration Worker

Good worker lenses:

• current behavior trace
• API or data contract map
• state model
• user workflow map
• abuse or failure cases
• operations, performance, or migration risk
• prior-art scan

Technical-Writing Editor

Use the first available entry.

Workflow

1. SET_SCOPE
2. LOAD_CONTEXT
3. MAP_SPACE
4. RUN_EXPLORATION_LOOP
5. FINISH_OR_CONTINUE

SET_SCOPE

• Treat exploration as knowledge finding.
• Explore the problem space, solution space, existing system, constraints, tradeoffs, decisions, risks, and open questions.
• Name the subject and boundary of the exploration.
• If the request revises an existing design artifact, use that existing design path as the artifact path.
• Default to chat. Write an artifact only when the user asks for one or the understanding should outlive the conversation.

LOAD_CONTEXT

• Use skill: ts-project-context to load shared facts and decisions.
• Read repo files, docs, configs, prior plans, prior designs, AGENTS.md, and external references when they change the understanding.
• Use principle detail docs as lenses for the topic.

MAP_SPACE

Build the smallest useful map:

• problem or decision
• users, actors, readers, or operators
• current state
• domain terms
• states and transitions
• boundaries and ownership
• contracts and long-lived interfaces
• constraints
• assumptions
• risks and edge cases
• unknowns

Adapt the map to the topic. A general problem space may need taxonomy, principles, tradeoffs, history, or competing frames. A product workflow may need actors, states, failure modes, and constraints.

RUN_EXPLORATION_LOOP

Repeat until the exploration is clear enough, the user pauses, or the requested scope changes:

1. ASK_QUESTIONS
2. SYNTHESIZE
3. EDIT_TECHNICAL_WRITING
4. CHECK_GATES
5. WRITE_ARTIFACT

For written artifacts, write early and keep the design document current after each meaningful synthesis. The user should be able to stop and resume from the artifact without losing important context.

ASK_QUESTIONS

• Ask only questions whose answers change the understanding.
• Prefer one critical question over several weak ones.
• Keep question batches answerable and purposeful.
• Explain what decision or uncertainty each question unlocks when useful.
• Stop asking when the next synthesis step is clear enough.

SYNTHESIZE

Give each material item a disposition:

• accepted fact
• source-owned contract
• constraint
• decision
• non-binding example
• implementation implication
• assumption
• open question
• out of scope
• risk
• follow-up exploration target

Use these categories while reasoning. Do not copy their names into the artifact unless a label helps the reader find or compare information.

Before writing, classify each concrete implementation statement as a decision, constraint, example, implementation implication, or planning note. Exclude planning notes from durable artifacts.

When a concrete implementation choice is a design decision, explain the reason or context that makes it part of the design. Do not leave it as a task command.

Resolve disagreements and contradictions when possible. Preserve them as open questions or risks when they remain unresolved. When saving artifacts, retain reusable conclusions in project context.

EDIT_TECHNICAL_WRITING

• Skip only for chat-only exploration with no written artifact.
• Before writing or updating an artifact, spawn a technical-writing editor sub-agent with skill: ts-technical-writing.
• The editor owns prose, structure, headings, bullets, examples, and llm-ism removal.
• The editor edits the artifact draft directly. It must return the edited artifact text, not review findings or suggestions.
• The editor must preserve meaning, exact technical names, facts, decisions, scope, source links, line references, contracts, assumptions, risks, and open questions. It may rewrite abstract labels and workflow terms.
• The judge must not perform the technical-writing edit itself. The judge may make factual corrections after the edit.
• If factual corrections materially rewrite the artifact, run the editor again.
• The editor prompt must include:
  • skill: ts-technical-writing
  • the reader and artifact purpose
  • the full draft or artifact path
  • the source constraints that must not change
  • the rule that the editor is not a reviewer and must edit directly

CHECK_GATES

At each synthesis point, verify:

• The synthesis answers the requested exploration scope.
• The confidence level matches the evidence gathered.
• Assumptions are labeled.
• Open questions are real unresolved unknowns.
• Remaining uncertainty is clear enough for the user to decide whether to keep exploring.

For written artifacts, also verify:

• A technical-writing editor edited the artifact after the latest material synthesis.
• The artifact stands alone without prior chat.
• Section choices fit the topic.

WRITE_ARTIFACT

• For chat output, summarize the current understanding, tradeoffs, risks, and open questions.
• For written output, create docs/designs/ if needed, then create or update: <repository-root>/docs/designs/YYYY-MM-DD_HH:MM_<design-name>.md.
• When updating an existing design, write back to the existing artifact path. Do not create a revised copy.
• Rewrite the whole artifact on each update so it reads as the current source of truth.
• When source files or reference docs own a contract, link to the owner with line numbers and summarize only the facts the reader needs. Do not inline copied source contracts, generated output, schemas, or command definitions unless the source is unavailable or the snippet is explicitly illustrative.
• State decisions in the system's own words. Explain the reason in the next sentence or bullet. Use labels such as Constraint or Risk only when they help the reader scan the document.
• Avoid roadmap and task-order language such as next, before, for v1, V1 should, and step sequencing unless sequencing itself is a design constraint.

Artifact Shape

Do not force a standard section list.

Use domain- or problem-specific sections. Headings should use names from the domain or system. Name the topic or decision, not a workflow category from this skill.

Each section should state what the reader needs to know about its topic. Include decisions, reasons, risks, assumptions, and open questions when they apply. Do not repeat the whole checklist in every section.

Write short paragraphs and direct sentences. Do not pack context, a decision, its reason, and its risks into one sentence. Prefer concrete examples over abstract framing. Cut filler, transition phrases, roadmap language, and empty setup.

The first section after the title should state the problem, what is known, and which choices remain open. Do not write a task list or roadmap.

Preserve:

• contracts owned by source files or reference docs, linked rather than copied;
• decisions and their reasons;
• rejected or deferred options when they clarify the decision space;
• risks, edge cases, assumptions, and open questions.

Omit empty sections.

FINISH_OR_CONTINUE

• Continue exploration when useful questions remain.
• Stop when the requested scope is understood well enough, or when remaining uncertainty is explicit.
• If chat exploration has produced durable context, ask whether to save it.