Clarify Knowns
Definition
Capture what is already true so the agent does not rediscover obvious context or make wrong assumptions. This skill asks questions first, then records reliable facts in UNKNOWNS.md.
Questions To Ask
- What are we trying to accomplish?
- What do you already know about the problem, codebase, domain, or tool?
- What has already been decided?
- What constraints should I respect?
- What existing files, examples, docs, designs, tickets, logs, or previous attempts matter?
- What should I treat as out of scope?
Question Rules
- Ask only questions that establish facts needed for the next phase.
- Ask one at a time when an answer could change direction.
- Use project inspection for facts the repository can answer better than the user.
- Record confidence and source for each known.
Existing Project Comparison
- Compare user-stated facts with existing project files and durable docs when available.
- Flag contradictions between user intent, code, tests, docs, and configuration.
- Convert stable project facts into
Known Knowns.
Suggestive Plan
- Identify the current work type.
- Ask for outcome, decisions, constraints, and relevant references.
- Inspect obvious project documents when available.
- Record facts, sources, confidence, and contradictions in
UNKNOWNS.md.
- Hand unresolved items to
$surface-questions.
Example
For a database redesign, ask what data must be preserved, which tables are in scope, what migrations already exist, and whether downtime is allowed.
Vocabulary
- Known known: fact already established or discoverable.
- Constraint: boundary the solution must respect.
- Source: user statement, file, test, doc, log, or external reference.
- Confidence: how reliable a known appears to be.
Expected Outcome
Produce a clear Known Knowns section in UNKNOWNS.md with outcome, decisions, constraints, relevant references, confidence, contradictions, and out-of-scope boundaries.
1---2name: clarify-knowns3description: Ask question-first prompts to capture known knowns before software work. Use for any domain when establishing the outcome, existing facts, decisions, constraints, project state, references, and user context before planning, designing, debugging, building, or auditing.4---56# Clarify Knowns78## Definition910Capture what is already true so the agent does not rediscover obvious context or make wrong assumptions. This skill asks questions first, then records reliable facts in `UNKNOWNS.md`.1112## Questions To Ask1314- What are we trying to accomplish?15- What do you already know about the problem, codebase, domain, or tool?16- What has already been decided?17- What constraints should I respect?18- What existing files, examples, docs, designs, tickets, logs, or previous attempts matter?19- What should I treat as out of scope?2021## Question Rules2223- Ask only questions that establish facts needed for the next phase.24- Ask one at a time when an answer could change direction.25- Use project inspection for facts the repository can answer better than the user.26- Record confidence and source for each known.2728## Existing Project Comparison2930- Compare user-stated facts with existing project files and durable docs when available.31- Flag contradictions between user intent, code, tests, docs, and configuration.32- Convert stable project facts into `Known Knowns`.3334## Suggestive Plan35361. Identify the current work type.372. Ask for outcome, decisions, constraints, and relevant references.383. Inspect obvious project documents when available.394. Record facts, sources, confidence, and contradictions in `UNKNOWNS.md`.405. Hand unresolved items to `$surface-questions`.4142## Example4344For a database redesign, ask what data must be preserved, which tables are in scope, what migrations already exist, and whether downtime is allowed.4546## Vocabulary4748- Known known: fact already established or discoverable.49- Constraint: boundary the solution must respect.50- Source: user statement, file, test, doc, log, or external reference.51- Confidence: how reliable a known appears to be.5253## Expected Outcome5455Produce a clear `Known Knowns` section in `UNKNOWNS.md` with outcome, decisions, constraints, relevant references, confidence, contradictions, and out-of-scope boundaries.
harsh817