Etak builds two linked graphs, one for discovery and one for development. Each node is an artifact: a typed, linked markdown file with a YAML header. This reference describes both sets.
| Artifact | Role in the graph |
|---|---|
| Objective | Business outcome the team is responsible for |
| Opportunity | Customer need framed as a how might we question |
| Idea | Proposed solution that addresses an opportunity |
| Assumption | Testable belief that must be true for an idea to work |
| Experiment | Test that produces evidence about an assumption |
| Critique | Structured examination of an idea or opportunity from an outside perspective |
| Memo | In-depth analytical document that informs the opportunity space |
The discovery artifact set is intentionally open. These seven types are the current shape of the discovery model, not a closed enumeration. As Etak's discovery discipline evolves — and as practice reveals artifact shapes that are systematically absent — new types will be added. Each addition ships as a file-based schema doc (here in docs/artifacts/) and as a graph node type in the data model simultaneously, so both representations stay in lockstep. Future additions follow the same discipline.
objective
↑ supports
opportunity
↑ addresses
idea
↓ assumed_by (inverse of)
assumption
↓ tests (inverse of)
experiment
Opportunities support one or more objectives. Ideas address one or more opportunities. Assumptions are held by one or more ideas. Experiments test one or more assumptions. The graph is not a tree — an idea can serve multiple opportunities, an assumption can underlie multiple ideas, and an experiment can inform multiple assumptions. That is deliberate. See foundations on why the graph model is honest about shared structure that a tree cannot represent.
Memos sit outside the main hierarchy. They connect via supports to objectives or opportunities they inform, but they are not required to link anywhere — a foundational memo may inform the whole space rather than a specific artifact.
Discovery artifacts are written to docs/discovery/ in your repo, one subdirectory per type:
docs/discovery/
objectives/
opportunities/
ideas/
assumptions/
experiments/
critiques/
memos/
Each file is a markdown document with a YAML frontmatter header. The header carries the typed fields (name, status, relationships). The body holds free-form description, evidence, context. Both are readable and editable without Etak.
When a validated idea moves into execution, work is tracked as a second graph under docs/development/. The development graph has a containment hierarchy (project, epic, story, task), plus parallel tracks and sync points (workstream, milestone), design artifacts (spec, ADR), time-boxed investigation (spike), and standalone work items (bug, chore, enhancement).
| Artifact | Role in the graph |
|---|---|
| Project | Bounded deliverable; the coordination hub for most work |
| Epic | Themed group of related stories |
| Story | User-frame increment with testable acceptance criteria |
| Task | Engineering-frame technical change. Optional. |
| Workstream | Parallel delivery track within a project |
| Milestone | Sequenced project checkpoint, thin and demo-able |
| Spec | Grounded technical design for a project, epic, or story |
| ADR | Hard-to-reverse architectural decision |
| Spike | Time-boxed investigation with a concrete outcome |
| Bug | Standalone defect |
| Chore | Standalone maintenance |
| Enhancement | Small standalone improvement |
project ──── workstreams ──── milestones
│ parent
▼
epic
│ parent
▼
story
│ parent (optional)
▼
task
Project, epic, story, and task form the containment hierarchy: one parent, one owner at each level. Workstream and milestone cut across the hierarchy; an epic or story lives in one workstream and may target one milestone. Specs and ADRs attach to a work item via for, not parent. Spikes, bugs, chores, and enhancements stand alone unless they reference a related work item.
A story describes a change from the user's point of view: persona, capability, outcome, testable ACs. A task describes a change to the system: files, schemas, interfaces. When a story's implementation is obvious from the ACs and a glance at the codebase, tasks add ceremony without adding clarity. Create tasks when the technical work isn't user-visible (migrations, feature flags, telemetry), when multiple PRs close a story, when a technical change enables multiple stories (parent to the epic), or when decomposition is real design work. Otherwise, implement the story directly.
Every development artifact can carry a from_discovery field that links back to a validated idea in docs/discovery/. The link is one-way: development points back; discovery never points forward. This matches how compliance audit trails work in practice, where changes to production systems trace back to the change request that initiated them.
Populate from_discovery on the development artifact that first takes up the work, usually a project or story. Omit for bugs, chores, and enhancements that originate in production or engineering judgment.
Development artifacts are written to docs/development/ in your repo, organized by type:
docs/development/
projects/
epics/
stories/
tasks/
work-items/ # bug, chore, enhancement
spikes/
specs/
adrs/
workstreams/
milestones/
Same shape as discovery artifacts: markdown body with YAML frontmatter. The authoritative schema for each type lives in the corresponding per-type reference under develop/skills/artifacts/ (e.g., spec.md, adr.md). Cross-cutting concerns — common fields, typed links, status lifecycles — are in model.md.
Every artifact is part of an evolving model of your team's current understanding. It is not a specification of reality. It is not a comprehensive catalog of every need or idea. It is what you know, what you believe, and what you've chosen to track, at a given moment.
The graph is messy on purpose. It has missing links. It has ideas with no assumptions under them because nobody has thought hard enough yet about how they might fail. It has opportunities that were promising six months ago and quietly went stale. This is not a bug. It is an accurate reflection of what real discovery looks like. The tool's job is to help you see the state clearly, not to paper over it.
See foundations for the longer argument.
- Develop overview — the upstream view of the development graph.
- Skills reference — the skills that create, modify, and propagate artifacts.
- Quick start — how to build your first artifacts.
- Getting started tutorial — walkthrough that produces each artifact type.