Processes · Knowledge-driven development, part 2 of 5
Four marks
Knowledge-driven development, part 2: here be dragons, and nowhere else
Seeded September 2026 Written October 2026
Knowledge-driven development is an experiment of mine, and it isn't battle-tested yet. Part 1 says where it started.
Medieval cartographers almost never wrote "here be dragons" on their maps. As far as anyone can tell, exactly one surviving globe does it, in Latin, somewhere off the coast of Asia. Everywhere else, the unknown was just left blank, or decorated with a sea monster and a shrug.
That's still one globe more than most backlogs. A ticket tracker tells you what someone intended to build. It doesn't tell you, standing in a particular corner of the system, whether the ground under your feet has been surveyed.
The marks started with a few hundred Asana tasks. I was looking at them, realized they were doing more harm than good, and decided I wanted a format that was more concise, and of value in other ways as well.
Knowledge-driven development is mostly a vocabulary for that. It has four marks.
1. The four marks
| Mark | Means |
|---|---|
| ✅ | Implemented and verified. The behavior exists and someone has seen its tests pass. |
| ⚠️ | Not implemented. The sentence describes the intended behavior. Nothing behind it works yet. This is the backlog item. |
| ❌ | Implemented but broken. A known defect. |
| ⛔ | Blocked. The gap marked just before it can't be closed from here. Always follows a ⚠️ or ❌, never stands alone, and always says what would unblock it. |
In map terms: ✅ is surveyed land. ⚠️ is here be dragons. ❌ is the bridge that's on the map and isn't in the river. ⛔ is a road closed by somebody else's council, with a sign saying what has to happen before it reopens.
The mark goes on the smallest statement that is wholly true or wholly false. A section heading carrying one ⚠️ for eleven paragraphs, nine of which work, is worse than no mark at all, because it makes the two broken paragraphs unfindable. A bullet takes the mark at the start of the bullet. A paragraph takes it at the start of the sentence that's untrue, not at the start of the paragraph.
2. The mark is the whole commentary
You write the sentence as the system should be, in the present tense, in the detail someone would need to use it. You mark it. Then you stop. You don't explain the mark. No "what it does instead", no "the customer currently sees", no account of how you found out. The glyph already says this sentence is not true yet. A paragraph restating that in prose turns a specification back into a bug report, which is the thing the page replaced.
The instinct runs the other way. A page that just cost somebody a day of debugging wants to say so. It mustn't. The incident goes in the changelog entry that introduced the mark, and the diagnosis goes in the pull request that fixes it. What the page owes its reader is the sentence they can build against, and one glyph telling them whether to trust it.
An ⚠️ that says "not implemented" is worthless. An ⚠️ that describes the intended behavior is a specification a cheaper agent can implement from. Its quality bar is that an agent can build from it without asking much. The mark is metadata. The paragraph is the deliverable.
3. ✅ is expensive on purpose
✅ may only be written by someone who has read the code and seen the tests pass. A plan saying so doesn't count, and neither does an agent reporting success or a pull request merging.
That's the strictest mark in the convention, because ✅ is the one readers build on.
4. Graduation
When a document contains no ⚠️ and no ❌, every ✅ in its body is deleted. The status link at the top is replaced by one line, carrying the page's only green check:
✅ This component is fully implemented, tested and free of known defects.
A page covered in green ticks is a page that has stopped carrying information. The ticks only ever existed to make the gaps legible, so when the gaps go, the ticks go with them. Nobody stamps "surveyed" on every hill of a finished map. One stamp on the cover will do.
Graduation is what keeps the marked part of the corpus small enough to stay true. A convention that only ever adds marks becomes wallpaper, and nobody reads wallpaper. A fully implemented, defect-free document carries one mark, by its status line, which is what most documents should eventually look like, and why a page with marks in its body is worth stopping on.
Here be dragons, then. But only where there are dragons, only on the square of the map where they live, and with a description of the dragon detailed enough that someone could build it.