FOR NEW TEAMMATES. AND THE PEOPLE EXPLAINING EVERYTHING.
“Best ask Thomas.” Thomas left in March.
The first weeks are made of questions answered a hundred times — out loud, so nowhere. With FACET the answer sits next to the code it explains. The new hire looks it up instead of waiting.
ASK ATLAS
When does a cancelled contract end?
- reading contracts/lifecycle/cancellation.yaml
- reading src/contracts/cancel.go
- reading test/contracts/cancel_test.go
At the end of the current contract period, not immediately. Cancelling sets ends_at to the period end; the contract stays active until then.
Sources
- Scenario
- cancellation-ends-at-period-end
- Code
- src/contracts/cancel.go:42
- Test
- cancel_test.go › ends at period end
Illustrative sketch · drawn from components, not a screenshot
FOUR QUESTIONS ON DAY ONE
Four questions. The same ones every week.
Who knows this? Where is it written? Why is it like this? Is it still true? For each of these, a feature in FACET has a fixed place — next to the code, not in three people’s heads.
Who knows this?
lineageThe feature’s owner is in the record, along with what it depends on and what depends on it.
Where is it written?
anchorEvery source file implementing the feature carries a @facet: anchor. The record points back at them.
Why is it like this?
intent · knowledgeIntent says what the feature is for. Knowledge answers the questions users ask about it.
Is it still true?
verificationWhich test proves which scenario. When the code changes without the record, facet drift reports it.
The seven facets of a record: intent, contract, anchor, verification, observation, knowledge, lineage
HANDOFF
Thomas is gone. What he knew isn’t.
FACET keeps what a feature is supposed to do, where it lives in the code and which test checks it. New teammates and new agents start there instead of interrupting the most experienced developers with every question.
id: contracts/lifecycle/cancellationintent: summary: A cancelled contract runs to the end of its current period.knowledge: common_pitfalls: question: What mistakes do users typically make? answer: Expecting access to stop on the day they cancel. success_signal: question: How does the user know it worked? answer: The contract shows its end date instead of a renewal date.
Illustrative example · an excerpt, not a complete record
Who reads the same record
- The new teammate, on day one, without interrupting anyone.
- The coding agent, before it touches the cancellation logic.
- The person who used to explain it every time — now only where the record is silent.
WHAT FACET DOES NOT DO HERE
An open question stays visibly open.
Unanswered questions stay unanswered until someone adds the knowledge.