--- name: discoverability-audit description: A skill for the engineers and operators of a Discoverability Engineering system, which audits the repository and live public surfaces and returns a status for each required capability, with proof, what is missing, and the smallest fixes in order. Use this skill when the user wants the recurring audit of a Discoverability Engineering system run against its repository and live public surfaces. Inputs include the whole repository (specs, state, actionboard, audits), the live public pages and registrations listed in the surface files, and the previous audit. For each required capability the skill returns IMPLEMENTED, PARTIAL, PLANNED, MISSING, or UNCLEAR, cites a stored record or a live page as proof, says what is missing or what evidence would settle each PARTIAL or UNCLEAR, and ends with the smallest fixes in order and who owns each. It covers the finder specifications, the question library, surfaces, the evidence graph, entity consistency, answer and agent tests, government and portal surfaces, engagement paths and inbound, the Actionboard, prior art and patent evidence, and the loop's acceptance criteria. Triggers on requests like "run the discoverability audit," "audit the discoverability system," "what does our repository say we run and what actually runs," "monthly audit," "is the first loop working," or "audit after the re-test." --- # Discoverability Audit This skill is Labor as Code™ for the discoverability audit in *Discoverability Engineering*. Labor as Code is a skill that encapsulates a person's knowledge, judgment, and skill in durable, inspectable, versioned form. The know-how is an engineer's habit of asking of every claim that the system does something, "Show me the record that says it ran." The method comes from "Controlled Tests and the Actionboard Show Whether Discovery Is Getting More Correct," which defines the five statuses and the September 24 report, and from the audit box that ends each implementation chapter. Read the first for the rule and the others for the checks each chapter adds. This skill runs every one of those checks in one pass over the user's own repository. It does not retell Merriden's audit. **A document is intent, not proof.** A spec, a plan, or an issue that says a check runs is evidence that someone meant it to. The skill marks a capability IMPLEMENTED only when a stored record shows it ran, or a live page shows the work. It never raises a status because a spec is well written, because a person says it is done, or because it ran once long ago. It never changes any file outside `state/audits/`. ## Before running Confirm these points with the user before the first status: 1. **Which subject.** The audit covers one subject and its Finder Specifications. Read `README.md` and `AGENTS.md` for the subject and the outcome. Stop and ask if there are several. 2. **The last audit.** Read the newest file in `state/audits/` named `discoverability-audit-*.md`. This run compares against it. If there is none, this is the first audit, and every status starts from the records alone. 3. **Who owns what.** Read the ownership section of `AGENTS.md`. Each finding names the engineer or the Discoverability Operator, using the book's split: the engineer owns the machine, the operator owns claims, questions, and inbound. 4. **Which optional parts apply.** The prior-art part applies only if the subject publishes disclosures or holds patents. The health supply-chain parts apply only where the specs name those surfaces. Mark a part NOT APPLICABLE with the reason. Never leave it silent. ## Step 1: Inspect what exists Read, and list by path, what the audit can see: 1. The repository: `specs/`, `state/`, `actionboard/`, `audits/`, `prompts/`, `content/`. 2. The live surfaces in `specs/surfaces/`: the website, the published documents, the structured data, the public profiles, the supplier portals and procurement records, and any patent and literature surfaces. Open each one that is public. Mark each surface that needs a login `manual_check` and name its owner. 3. The test records, the answer-engine outputs, the inbound records, the Actionboard, the ontology, and the evidence freshness dates. Record the date of the audit and the date each live surface was read. ## Step 2: Return a status for each capability Give each line one of five statuses and cite its proof: | Status | Meaning | | --- | --- | | IMPLEMENTED | The capability runs, and a stored record or live page shows it ran | | PARTIAL | Some of it runs. The line says which part is missing | | PLANNED | A spec or an issue describes it, and nothing runs yet | | MISSING | Neither a spec nor a running piece exists | | UNCLEAR | The audit cannot tell from the evidence it has, and the line says what would settle it | Check each capability below and cite a file path with a date, a record ID, or a live URL with the date read: 1. **Finder Specifications and jobs.** Every specification names a job, sources or UNKNOWN for each field, `cannot_use`, and a next action; every job has exclusions; no field uses persona language. 2. **Finder Question Library.** Every required criterion has a question; every question has a source, expected evidence, and a next action; no two questions pass or fail on the same evidence; the last review is inside its calendar. 3. **Surface map.** Every surface a finder uses has an entry with an owner, a holder, a band, and a `last_checked` date under 90 days; evidence readable only by a logged-in human is marked. 4. **Evidence graph.** Every claim node has a `demonstrated_by` link to a public artifact readable without a login; every record has a freshness limit; stale records and open `contradicted_by` links are listed. 5. **Entity consistency.** The canonical record exists; the last comparison of every surface is under 35 days old; each conflict has a queue item or a recorded reason. 6. **Ontology and structured data.** Terms from recent inbound and test results are in the ontology or listed as gaps; structured data values match visible text and the entity record; a record shows the check ran. 7. **Answer and agent tests.** The tests cover every surface the Finder Specification lists; each high-priority question runs in at least two phrasings; every run keeps the verbatim answer and its citations; every saved answer has characterization findings and all five scores; no report counts a mention as qualification. 8. **Government and portal surfaces.** Every entry has stale-when dates; renewal and expiry dates are on the Actionboard; the past-performance page explains what award data omits. 9. **Engagement paths and inbound.** Every next action has a matching path with an owner and a reply time; the last path test is under 35 days old; every inquiry has a record that closes with a spec change or a written reason; qualified and unqualified inquiries by path are on the Actionboard. 10. **Actionboard.** It answers each of its thirteen questions from stored records, was recomputed after the last test, and carries no traffic, rankings, or mention counts. Three sampled numbers trace to their records. 11. **Prior art and patent evidence** (if applicable). Every disclosure the subject relies on has a Prior Art Record with one date proven by someone other than the publisher and no login or notice; a retrieval test under 35 days old exists for each record; every invention made public has a Publish-or-Protect entry dated before its first public date; every patent node shows an assignee name equal to the legal name and a recorded assignment; the patent watch ran in the last 8 days; the Actionboard's prior-art row matches the last retrieval test. 12. **Acceptance criteria** for the first loop, written before the baseline: each returns a status against dated records, and the audit says whether any criterion blocks expansion. 13. **Where knowledge lives.** No prompt holds a criterion, list, or question text that a spec should hold. ## Step 3: Test the statuses against each other 1. Reject any IMPLEMENTED that cites only a spec file. Change it to PLANNED or PARTIAL and say why. 2. Read the audit next to the Actionboard. If scores rise while an audit line fails, say so and name which record to check first, because the scores may be produced wrongly. 3. Compare with the last audit. List each line whose status changed and the record that changed it. A line that got worse gets the same attention as a new gap. 4. Read the live pages for lines that rest on a live page. A record that says a page exists does not prove the page still does. ## Step 4: Write the report and conclude Save the report to `state/audits/discoverability-audit-.md`: ``` Discoverability audit, . Subject: . ``` Then conclude in plain words, with reasons: 1. **The count** of each status, and the change since the last audit. 2. **The three smallest fixes, in order,** each with the line it closes, the owner, and the observable change the next audit should show. Put a lapse a finder would see first (an expiring registration, a stale record behind a required criterion) ahead of a missing tool. 3. **What only a person can settle:** claims, questions, inbound decisions, and anything marked `manual_check`. 4. **Whether the loop can expand.** Say yes only when every acceptance criterion is IMPLEMENTED or the open ones are named as not blocking, with the reason. Where the evidence is too thin to give a status, write UNCLEAR and name what would resolve it. Do not pick a status to sound useful. ## What this skill does not do - It does not edit any spec, record, page, or registration, and it writes only to `state/audits/`. - It does not renew, publish, or correct anything it finds. - It does not count a mention, a ranking, or traffic as evidence that a finder could qualify the subject. - It does not decide whether to file, publish, or keep something secret, or read a patent's claims. The operator and the patent attorney do.