0. **Is this what it claims to be, and is it whole?** Valid JSON, or NDJSON, or
1. **What is in here?** List the fields, at every level.
2. **How deep does it go?**
3. **What is one record?** Name every defensible answer, not just the first, and
4. **Which fields are always present, and which are only sometimes?**
5. **Does any field change type between records?**
6. **Are any object keys actually data?**
7. **How many records are there**, under your answer to question 3?
8. **Pull three named fields into a table**, one row per record.
9. **Pull a field that is missing from some records** and keep those rows.
10. **Flatten the deepest array** into rows.
11. **Find every path whose value matches something**, such as an email or a URL.
12. **Turn the whole document into the flattest honest table**, and say what was
13. **Did you need to know the shape before writing the code?**
14. **Does the code survive the next file** of nominally the same kind, unchanged?
15. **Can you read it back a week later** without going to the reference?
16. **How many lines**, and how much of that is ceremony rather than intent?
17. **Does one vocabulary answer all three?** Where it does not, is the difference
18. **Which words worked at every depth?** Those are the candidates for the3 The fixed questions
Every file is asked the same questions, in every tool, or nothing is comparable. The list is QUESTIONS.md in the repository, and it is the specification for the vocabulary as much as it is the method:
A word belongs in
fathomonly if removing it makes one of the fixed questions unanswerable on at least one corpus file. No word is added without naming the question it answers and the file that proves it.
That makes the question list the vocabulary’s bound. It also explains why one existing library has roughly 180 exports and fathom expects to have a handful: that library answers questions nobody in this corpus asked.
3.1 Two rules that make the answers mean something
Score the exploring separately from the extracting. The whole premise is that exploring an unknown document is where the cost is and that nobody measures it. A session that records only how the extraction went has measured the half that was never in question. So for each file and tool: how long until you could state the shape, and what you had to run to get there.
A question added after the feature it describes is marked as such. Scoring another tool “cannot” on a question written to match something fathom had just decided to do is circular, and a reader needs to be able to tell those apart from the questions that predate the design.
3.2 “Cannot” is the most useful cell in the grid
A tool that cannot answer a question records that, with the reason, and moves on. An empty cell is the least useful thing an attempt file can contain, because it does not distinguish the tool refused from nobody tried.