Writing a method people can inspect
Replacing Arkah's custom-framework form with an editable method page made the reasoning itself easier to review.
A retrospective from the development history. Published .
A form can collect every field a system needs while making the thing being created difficult to understand.
That was the shape of the custom-framework editor Arkah replaced in early November. The replacement work began on November 4 and merged as a combined change on November 5: describe a method, inspect the draft, edit it as readable material, and try it on a question.
The important shift was what the person had in front of them. A framework is a way of thinking through a class of questions. The editing surface needed to make that way of thinking visible.
Suppose a team has a method for reviewing an incident. This is a fictional example. They first establish the timeline, separate observations from explanations, compare possible causes, and decide which follow-up work would test those explanations. A long configuration form could capture those sections. It would still make the reader assemble the method in their head from labels, controls and repeated settings.
Reading the method as a page changes the review. The team can notice that “possible causes” appears before the observations, or that the follow-up section asks only for implementation work and never asks how to test the cause. Those are problems with the method itself. They can be hard to see when each part is buried in its own editor.
The November change made text directly editable and kept the proposed arrangement visible beside it. It also put problems near the part of the method they concerned. A person shouldn’t have to translate a technical field name to work out which sentence needs attention.
Drafting from a description helps with the first version, but it introduces a new review task. The system can fill gaps that the person never meant to leave to it.
In the fictional incident method, it might assume that every incident has one cause, or that every hypothesis needs an assigned owner. The first assumption could distort the analysis. The second might be sensible for one team and excessive for another. Fluent prose doesn’t tell you whether either choice came from the person who described the process.
That makes the ability to inspect and revise the draft important. Arkah’s current public example shows a drafted method with questions about the assumptions it added. The useful next action is to settle those questions, then examine the resulting method before using it repeatedly.
Trying a method on one actual question can reveal different problems from reading it in the abstract. A section called “Evidence” sounds reasonable. Applied to an incident, it may need timestamps and observations. Applied to a vendor decision, it may need requirements and comparable source material. A broad label can conceal an unclear instruction until a concrete case reaches it.
A quick try has limits. It can show whether the structure makes sense for the example and whether the question fits. It doesn’t demonstrate that a full research process has been completed or that the method will behave well across every future case.
The editing details still matter. Automatic saving removes a button, but it also makes the save state part of the interface’s responsibility. If a change fails to save, the person needs to know before leaving. “The text is visible in the editor” and “the method has been saved” are separate facts, even when the happy path makes them feel like one action.
Hand the incident method to a colleague and ask them to point to the part they disagree with. That review is easier to have when the method is readable before it gets repeated in the next report.