146 lines
7.1 KiB
Markdown
146 lines
7.1 KiB
Markdown
# Repository Decisions
|
|
|
|
Why the repository is shaped the way it is. Each entry records the alternative that was considered
|
|
and the reason it lost, because a decision with no recorded alternative gets re-litigated by every
|
|
future contributor.
|
|
|
|
**When to read it:** before proposing a structural change, and when an existing rule looks arbitrary.
|
|
|
|
## Layout
|
|
|
|
**Decision: a skills repository with the skill under `skills/<name>/`, and everything else as
|
|
maintenance tooling.**
|
|
|
|
The alternative was a flat repository where the skill is the root. It loses on one specific point: the
|
|
gates, the tests and the evidence record are *about* the skill rather than part of it, and installing
|
|
the skill should not install them. The `skills/<name>/SKILL.md` layout is also what the installer
|
|
resolves, so the structure and the install mechanism are the same fact stated once.
|
|
|
|
**Decision: an agent preset is not involved, and no runtime is required.**
|
|
|
|
The skill is documents plus scripts. A background process, a server, or a plugin would each add a
|
|
failure mode that cannot be checked by reading a file, and none of them is needed to answer the
|
|
questions this skill answers.
|
|
|
|
## The strength vocabulary
|
|
|
|
**Decision: three grades — `observed`, `inferred`, `unverified` — applied to every factual claim.**
|
|
|
|
The alternative was ordinary prose, which reads as uniformly confident. The observed failure is not
|
|
that a reader disbelieves a claim; it is that a reader cannot tell a measured result from a plausible
|
|
one, and therefore builds a plan on top of an assumption.
|
|
|
|
Three grades rather than two, because the interesting middle case is real: a mechanism verified from
|
|
its documentation, exercised by nobody here. Calling that "unverified" hides that the mechanism is
|
|
known; calling it "verified" is a lie.
|
|
|
|
**Decision: missing coverage is recorded as `unknown`, never as absence.**
|
|
|
|
A search that returned nothing is evidence about the search. "The tool is not installed" and "the tool
|
|
does not exist" lead to different actions, and collapsing them is the most repeated data error in this
|
|
kind of record.
|
|
|
|
**Decision: a claim is only as strong as the weakest link in its chain.**
|
|
|
|
Stated separately because it is violated by composition rather than by any single sentence: a row that
|
|
joins a verified mechanism to an unexercised route reads as one verified claim unless the joining is
|
|
called out.
|
|
|
|
## The entry point
|
|
|
|
**Decision: `SKILL.md` stays near 300 lines, and the inventory lives in `references/routing.md`.**
|
|
|
|
The alternative was one large entry point. It loses because the entry point loads in full on every
|
|
activation: a lookup table that is read once per task is a poor use of that budget, while a
|
|
symptom-to-file mapping must stay one hop and therefore belongs there.
|
|
|
|
**Decision: the symptom index is mirrored into `routing.md`, with a gate comparing the two.**
|
|
|
|
Splitting a table is how two tables start disagreeing. A mirror plus a check gives a reader all three
|
|
tables in one load and makes drift a build failure rather than a slow decay.
|
|
|
|
**Decision: the entry point is a procedure with gates, not background reading.**
|
|
|
|
Because the observed failure mode is a reader agreeing with the material and then reasoning from
|
|
first principles anyway. Gates are actions with pass criteria precisely so that "I understand the
|
|
idea" cannot be mistaken for having done it.
|
|
|
|
## The scripts
|
|
|
|
**Decision: standard library only, Python 3.9+, no third-party imports.**
|
|
|
|
A parser used to build a toolchain must be readable and must run on a bare install, including in a
|
|
locked-down analysis VM. A dependency is a thing that can fail to install at the moment the analysis
|
|
is happening. Where a third-party tool is the right instrument, the script reports its absence
|
|
instead of substituting a weaker method.
|
|
|
|
**Decision: every structure offset is computed, never estimated.**
|
|
|
|
Two structures in the fixture generator overlapped because each had a hand-picked offset. A single
|
|
allocating cursor makes the overlap impossible rather than merely absent.
|
|
|
|
**Decision: a numeric table carries its source.**
|
|
|
|
A constant table written from recall was wrong in every entry and produced plausible output. Tables
|
|
taken from a specification name the specification; tables that read an undocumented structure say so.
|
|
|
|
**Decision: an unproven property is reported as unproven, not as satisfied.**
|
|
|
|
The length guard is the case that produced this rule: it compared a value with itself and could never
|
|
fail. A property the tool cannot establish — the length of a site without disassembling it — is now a
|
|
third state rather than a silent pass.
|
|
|
|
**Decision: fixtures are generated, not committed.**
|
|
|
|
A committed sample is a licensing and provenance problem, and a downloaded one makes the suite depend
|
|
on the network and on a target that changes. A generated fixture is deterministic, carries the awkward
|
|
cases deliberately, and is code rather than an artifact.
|
|
|
|
## The gates
|
|
|
|
**Decision: six structural gates at the repository root, and CI runs all of them.**
|
|
|
|
Consistency has a natural counter-pressure — a broken path fails loudly. Bloat and drift do not, which
|
|
is why there is a budget gate and a routing gate rather than only link checking. Every gate exists
|
|
because a specific class of change went unnoticed without it.
|
|
|
|
**Decision: the leak scanner owns its rules, and the repository gate delegates to it.**
|
|
|
|
One place to argue with an exemption list. A second implementation would diverge, and the diverging
|
|
one would be the one that ran.
|
|
|
|
**Decision: the claim that a document makes about a command is machine-checked against that script's
|
|
own argument table.**
|
|
|
|
A flag that no longer exists is drift no path check can see: the file resolves, the line number is
|
|
right, and the command fails at the moment someone follows the page instead of the tool.
|
|
|
|
## The hardware layer
|
|
|
|
**Decision: the hardware routes are probed per host and degraded honestly, rather than declared
|
|
supported.**
|
|
|
|
This is the skill's differentiator and its least portable part. A CPU reporting the feature says
|
|
nothing about whether a capture path is reachable, and a hypervisor present on the analysis host
|
|
changes what a debugger and a hardware breakpoint can do. A plan that assumes otherwise fails at the
|
|
first step and gets attributed to the tooling. The probe exists so the answer is a measurement.
|
|
|
|
**Decision: bits whose meanings are not verified are printed raw.**
|
|
|
|
Reading a capability out of a recollection is how a wrong plan becomes an authoritative-looking one.
|
|
There is no loss in printing the register values and letting the reader consult the processor
|
|
specification for the family in front of them.
|
|
|
|
## Publishing
|
|
|
|
**Decision: the desensitization rules state what must be removed *and* what must stay.**
|
|
|
|
A one-sided rule trains people to redact tool names and format names, which destroys the reusable part
|
|
of the material while removing none of the target's identity. A scanner that flags those gets switched
|
|
off, and then the real findings go with it.
|
|
|
|
**Decision: an entry-point document is treated as a prompt surface.**
|
|
|
|
A README, a case note, a screenshot filename — these carry target identity as easily as body text, and
|
|
they are the part most often forgotten because they were written before the material was.
|