Deep Discovery can begin with an established repository of requirements, a compact owner brief, or both. The goal is not to upload everything or make the owner answer an exhaustive questionnaire. It is to collect enough relevant evidence for local AI to propose a useful direction that the owner can correct.
Put source material in the owner-controlled folder
Use docs/discovery/sources/ for candidate source material. Packageable supporting sources are plain .md and .txt files.
Useful sources include:
- current procedures, forms, decision logs, and policy extracts
- data definitions, integration notes, and migration constraints
- incident, exception, and workaround notes
- focused owner or subject-matter-expert interview notes
- Markdown sidecars that accurately extract useful text from a binary original
Do not add secrets, credentials, private keys, generated tokens, or material you are not authorized to process.
Start with the same four questions
Open your selected Codex or Copilot chat and invoke the local discovery guidance:
- Codex:
$swarmcraft-discover - GitHub Copilot:
/discover
Every discovery starts with the same four questions, even when source documents already exist. The assistant asks them one at a time rather than displaying a form:
- an existing website, product, or repository when available
- the main problem and intended user in one sentence
- current software or integrations
- the preferred depth: Recommend, then refine (recommended), Balanced, or Detail first
After each answer, the provider records it in docs/discovery/sources/owner-interview.md and distributes its useful meaning into every affected discovery-document draft. It should not wait to reach a particular document or ask you to repeat the same knowledge later.
After question four, it asks you to add as much useful source material as you can and reply gathering is complete when ready—even when there is nothing else to add. It then inventories the interview record and supplied sources together. Only after that should it research the context you authorized, propose likely roles, workflows, records, integrations, constraints, and outcomes, and ask you to correct the proposal. On the recommended route it should build the first useful prototype after no more than one focused clarification round.
Handle PDFs and other binary originals
Binary files are never package inputs. Create a Markdown sidecar with the relevant extracted text and keep the original local for visual comparison. Confirm tables, diagrams, footnotes, and formatting-dependent meaning before treating the sidecar as reliable.
Use the sidebar's visual-review actions to compare the original and sidecar. The owner can record that review directly or ask local AI to help. The manifest stores timestamped review evidence without uploading the binary.
Select the exact supporting set
Use the Sources group in the Deep Discovery sidebar to inspect candidate, selected, unselected, and review-recommended material. Include or exclude each supporting source deliberately.
Selection invalidates the previous aggregate confirmation. Confirm the complete proposed set again before preparation. A changed or stale selected source blocks packaging rather than being silently dropped, truncated, or summarized.
Selected sources support the curated documents. They do not override a reviewed decision. Untracked or ignored selected text can be packaged, but Git will not back it up automatically; the owner remains responsible for local backup.
Continue with Review the nine Deep Discovery documents.