{"format": "ta-amps.seed-pack.nouns.v1", "pack_id": "docs-improvement", "status": "proposal_only", "records": [
{"store": "seedpack.docs-improvement", "key": "docs-improvement.v0.1.0.pack", "expected_version": 0, "producer_surface": "surface:tessera", "visibility_scope": "surface_only", "allowed_surfaces": [], "target_cohorts": ["all"], "tags": ["category:noun.skill_pack", "pack:docs-improvement", "role:pack", "content:authored", "spdx:MIT", "status:quarantined"], "value": {"category_id": "noun.skill_pack", "role": "pack", "pack": "docs-improvement", "pack_version": "0.1.0", "title": "A collection of nouns and verbs for making documentation clearer for a named reader", "lets_workers": "Make documentation easier to understand and act on: audit pages against a plain rubric for a named reader, find the missing pages, draft rewrites that keep every fact, run the examples and links, and have another worker check the result.", "flow": [{"verb": "docs-improvement.audit-docs", "when": "First, for a named reader persona."}, {"verb": "docs-improvement.find-gaps", "when": "After the audit."}, {"verb": "docs-improvement.draft-rewrite", "when": "Per page; tone choices can go through taste-palettes."}, {"verb": "docs-improvement.check-examples", "when": "Before and after rewrites; deterministic."}, {"verb": "docs-improvement.review-docs", "when": "Last, by a different worker."}], "rubric": {"store": "seedpack.docs-improvement", "key": "docs-improvement.v0.1.0.doc-rubric", "version": 1, "value_sha256": "cea0d59703e03d460d4de8f858ae0a96bbeb25c16508e59f99c6da8e3cd63e80"}, "publication": "Rewrites are drafts in the requester's scope. Committing, publishing or opening a pull request is the owner's separate act.", "status": "proposal", "admission": "not_admitted", "content_kind": "authored_guidance", "license": "MIT", "provenance": {"source": "original ta-amps authored proposal", "license": "MIT", "generator": "scripts/build_packs.py", "independently_verified": false}, "dimensions": {"determinism": 0.0, "evidence_grounding": 0.0, "token_efficiency": 0.0, "safety_compliance": 0.0, "verification_tier": "unverified"}, "dimension_basis": {"measured": false, "method": "unmeasured_floor", "reason": "Tessera requires these axes, so each is set to its lowest value and the tier is unverified. No quality is claimed. Replace them only with measured values and the evidence that produced them."}, "relations": [{"relation": "requires_noun", "target_id": "seedpack.docs-improvement/docs-improvement.v0.1.0.doc-rubric", "target_category": "noun.benchmark_suite", "note": ""}, {"relation": "requires_noun", "target_id": "seedpack.docs-improvement/docs-improvement.v0.1.0.template.reader-persona", "target_category": "noun.seed_hypothesis", "note": ""}, {"relation": "requires_noun", "target_id": "seedpack.docs-improvement/docs-improvement.v0.1.0.template.doc-audit", "target_category": "noun.eval_run", "note": ""}, {"relation": "requires_noun", "target_id": "seedpack.docs-improvement/docs-improvement.v0.1.0.template.doc-gaps", "target_category": "noun.seed_hypothesis", "note": ""}, {"relation": "requires_noun", "target_id": "seedpack.docs-improvement/docs-improvement.v0.1.0.template.rewrite", "target_category": "noun.public_source", "note": ""}, {"relation": "requires_noun", "target_id": "seedpack.docs-improvement/docs-improvement.v0.1.0.template.example-run", "target_category": "noun.eval_run", "note": ""}, {"relation": "requires_noun", "target_id": "seedpack.docs-improvement/docs-improvement.v0.1.0.template.review", "target_category": "noun.eval_run", "note": ""}]}},
{"store": "seedpack.docs-improvement", "key": "docs-improvement.v0.1.0.doc-rubric", "expected_version": 0, "producer_surface": "surface:tessera", "visibility_scope": "surface_only", "allowed_surfaces": [], "target_cohorts": ["all"], "tags": ["category:noun.benchmark_suite", "pack:docs-improvement", "role:rubric", "content:authored", "spdx:MIT", "status:quarantined"], "value": {"category_id": "noun.benchmark_suite", "role": "rubric", "pack": "docs-improvement", "pack_version": "0.1.0", "title": "Documentation rubric: eight criteria", "category_reason": "A fixed scoring rubric every audit and review uses.", "criteria": [{"id": "first-screen", "asks": "The first screen says who it is for, what it does and how to try it.", "evidence": "Quote the first 30 lines and name what is missing."}, {"id": "one-reading-order", "asks": "A newcomer can tell which page to read first and next.", "evidence": "List entry pages and the order each one gives."}, {"id": "task-coverage", "asks": "The first tasks readers try each have a page.", "evidence": "Map likely first tasks to pages."}, {"id": "runnable-examples", "asks": "Copy-paste examples run as written.", "evidence": "Run each code block in a sandbox and record pass, fail or not runnable."}, {"id": "plain-language", "asks": "Sentences are short, terms are defined where first used, and outcomes come before mechanisms.", "evidence": "Quote the worst passages with a plain rewrite."}, {"id": "honest-status", "asks": "Claims about what works match the evidence; dated status beats timeless claims.", "evidence": "Cite each stale or unsupported claim and the evidence that contradicts it."}, {"id": "working-links", "asks": "Local links resolve and external links name what they point to.", "evidence": "List broken local links; external links are checked only when allowed."}, {"id": "accessible-structure", "asks": "Headings are in order, images have text alternatives and tables have headers.", "evidence": "List each structural problem with its location."}], "levels": {"good": "Meets the criterion with no material gap.", "needs_work": "A gap a reader would notice; fixable in place.", "broken": "Misleads readers or blocks a first task."}, "rules": ["Judge for the named reader, not for the author.", "A rewrite keeps every fact, command and number; it changes words, order and structure.", "Status claims need evidence with a date."], "status": "proposal", "admission": "not_admitted", "content_kind": "authored_guidance", "license": "MIT", "provenance": {"source": "original ta-amps authored proposal", "license": "MIT", "generator": "scripts/build_packs.py", "independently_verified": false}, "dimensions": {"determinism": 0.0, "evidence_grounding": 0.0, "token_efficiency": 0.0, "safety_compliance": 0.0, "verification_tier": "unverified"}, "dimension_basis": {"measured": false, "method": "unmeasured_floor", "reason": "Tessera requires these axes, so each is set to its lowest value and the tier is unverified. No quality is claimed. Replace them only with measured values and the evidence that produced them."}, "relations": []}},
{"store": "seedpack.docs-improvement", "key": "docs-improvement.v0.1.0.template.reader-persona", "expected_version": 0, "producer_surface": "surface:tessera", "visibility_scope": "surface_only", "allowed_surfaces": [], "target_cohorts": ["all"], "tags": ["category:noun.seed_hypothesis", "pack:docs-improvement", "role:template", "content:authored", "spdx:MIT", "status:quarantined"], "value": {"category_id": "noun.seed_hypothesis", "role": "template", "pack": "docs-improvement", "pack_version": "0.1.0", "title": "Template: the reader the docs are judged for: who they are, what they want in a minute, what they know", "category_reason": "A persona is an assumption about the reader that audits and readers' feedback can test.", "describes": "the reader the docs are judged for: who they are, what they want in a minute, what they know", "schema": {"type": "object", "additionalProperties": false, "required": ["who", "wants_in_one_minute", "already_knows", "does_not_know"], "properties": {"who": {"type": "string", "minLength": 1, "maxLength": 200}, "wants_in_one_minute": {"type": "string", "minLength": 1, "maxLength": 300}, "already_knows": {"type": "array", "minItems": 0, "maxItems": 8, "items": {"type": "string", "minLength": 1, "maxLength": 200}}, "does_not_know": {"type": "array", "minItems": 1, "maxItems": 8, "items": {"type": "string", "minLength": 1, "maxLength": 200}}}}, "rules": ["One persona per audit."], "example": {"who": "SYNTHETIC: a developer evaluating the project during a hackathon", "wants_in_one_minute": "Whether it solves their problem and the first command to try", "already_knows": ["git", "Python"], "does_not_know": ["The project's vocabulary", "Which page to read first"]}, "status": "proposal", "admission": "not_admitted", "content_kind": "authored_guidance", "license": "MIT", "provenance": {"source": "original ta-amps authored proposal", "license": "MIT", "generator": "scripts/build_packs.py", "independently_verified": false}, "dimensions": {"determinism": 0.0, "evidence_grounding": 0.0, "token_efficiency": 0.0, "safety_compliance": 0.0, "verification_tier": "unverified"}, "dimension_basis": {"measured": false, "method": "unmeasured_floor", "reason": "Tessera requires these axes, so each is set to its lowest value and the tier is unverified. No quality is claimed. Replace them only with measured values and the evidence that produced them."}, "relations": []}},
{"store": "seedpack.docs-improvement", "key": "docs-improvement.v0.1.0.template.doc-audit", "expected_version": 0, "producer_surface": "surface:tessera", "visibility_scope": "surface_only", "allowed_surfaces": [], "target_cohorts": ["all"], "tags": ["category:noun.eval_run", "pack:docs-improvement", "role:template", "content:authored", "spdx:MIT", "status:quarantined"], "value": {"category_id": "noun.eval_run", "role": "template", "pack": "docs-improvement", "pack_version": "0.1.0", "title": "Template: an audit of a set of pages: issues with locations and evidence, and a level per criterion", "category_reason": "An audit is a scored run of the rubric over the pages.", "describes": "an audit of a set of pages: issues with locations and evidence, and a level per criterion", "schema": {"type": "object", "additionalProperties": false, "required": ["pages", "issues", "scores"], "properties": {"pages": {"type": "array", "minItems": 1, "maxItems": 100, "items": {"type": "string", "minLength": 1, "maxLength": 300}}, "issues": {"type": "array", "minItems": 0, "maxItems": 200, "items": {"type": "object", "additionalProperties": false, "required": ["criterion", "location", "level", "evidence", "suggestion"], "properties": {"criterion": {"type": "string", "enum": ["first-screen", "one-reading-order", "task-coverage", "runnable-examples", "plain-language", "honest-status", "working-links", "accessible-structure"]}, "location": {"type": "string", "minLength": 1, "maxLength": 300}, "level": {"type": "string", "enum": ["needs_work", "broken"]}, "evidence": {"type": "string", "minLength": 1, "maxLength": 600}, "suggestion": {"type": "string", "minLength": 1, "maxLength": 600}}}}, "scores": {"type": "array", "minItems": 8, "maxItems": 8, "items": {"type": "object", "additionalProperties": false, "required": ["criterion", "level"], "properties": {"criterion": {"type": "string", "enum": ["first-screen", "one-reading-order", "task-coverage", "runnable-examples", "plain-language", "honest-status", "working-links", "accessible-structure"]}, "level": {"type": "string", "enum": ["good", "needs_work", "broken"]}}}}}}, "rules": ["Every issue cites a file and line or a heading.", "Every criterion gets exactly one level."], "status": "proposal", "admission": "not_admitted", "content_kind": "authored_guidance", "license": "MIT", "provenance": {"source": "original ta-amps authored proposal", "license": "MIT", "generator": "scripts/build_packs.py", "independently_verified": false}, "dimensions": {"determinism": 0.0, "evidence_grounding": 0.0, "token_efficiency": 0.0, "safety_compliance": 0.0, "verification_tier": "unverified"}, "dimension_basis": {"measured": false, "method": "unmeasured_floor", "reason": "Tessera requires these axes, so each is set to its lowest value and the tier is unverified. No quality is claimed. Replace them only with measured values and the evidence that produced them."}, "relations": []}},
{"store": "seedpack.docs-improvement", "key": "docs-improvement.v0.1.0.template.doc-gaps", "expected_version": 0, "producer_surface": "surface:tessera", "visibility_scope": "surface_only", "allowed_surfaces": [], "target_cohorts": ["all"], "tags": ["category:noun.seed_hypothesis", "pack:docs-improvement", "role:template", "content:authored", "spdx:MIT", "status:quarantined"], "value": {"category_id": "noun.seed_hypothesis", "role": "template", "pack": "docs-improvement", "pack_version": "0.1.0", "title": "Template: the first tasks the reader would try that no page covers", "category_reason": "Gaps are hypotheses about what readers need.", "describes": "the first tasks the reader would try that no page covers", "schema": {"type": "object", "additionalProperties": false, "required": ["gaps"], "properties": {"gaps": {"type": "array", "minItems": 1, "maxItems": 20, "items": {"type": "object", "additionalProperties": false, "required": ["task", "reader", "missing", "priority"], "properties": {"task": {"type": "string", "minLength": 1, "maxLength": 200}, "reader": {"type": "string", "minLength": 1, "maxLength": 200}, "missing": {"type": "string", "minLength": 1, "maxLength": 400}, "priority": {"type": "integer", "minimum": 1, "maximum": 3}}}}}}, "rules": ["Each gap names the task and what is missing."], "status": "proposal", "admission": "not_admitted", "content_kind": "authored_guidance", "license": "MIT", "provenance": {"source": "original ta-amps authored proposal", "license": "MIT", "generator": "scripts/build_packs.py", "independently_verified": false}, "dimensions": {"determinism": 0.0, "evidence_grounding": 0.0, "token_efficiency": 0.0, "safety_compliance": 0.0, "verification_tier": "unverified"}, "dimension_basis": {"measured": false, "method": "unmeasured_floor", "reason": "Tessera requires these axes, so each is set to its lowest value and the tier is unverified. No quality is claimed. Replace them only with measured values and the evidence that produced them."}, "relations": []}},
{"store": "seedpack.docs-improvement", "key": "docs-improvement.v0.1.0.template.rewrite", "expected_version": 0, "producer_surface": "surface:tessera", "visibility_scope": "surface_only", "allowed_surfaces": [], "target_cohorts": ["all"], "tags": ["category:noun.public_source", "pack:docs-improvement", "role:template", "content:authored", "spdx:MIT", "status:quarantined"], "value": {"category_id": "noun.public_source", "role": "template", "pack": "docs-improvement", "pack_version": "0.1.0", "title": "Template: a draft rewrite of one page as a patch, explaining which issue each change fixes", "category_reason": "A rewrite is documentation content pinned to the page version it changes.", "describes": "a draft rewrite of one page as a patch, explaining which issue each change fixes", "schema": {"type": "object", "additionalProperties": false, "required": ["target", "before_sha256", "patch", "explains"], "properties": {"target": {"type": "string", "minLength": 1, "maxLength": 300}, "before_sha256": {"type": "string", "pattern": "^[0-9a-f]{64}$"}, "patch": {"type": "string", "minLength": 1, "maxLength": 16000}, "explains": {"type": "array", "minItems": 1, "maxItems": 40, "items": {"type": "object", "additionalProperties": false, "required": ["issue_ref", "change"], "properties": {"issue_ref": {"type": "string", "minLength": 1, "maxLength": 300}, "change": {"type": "string", "minLength": 1, "maxLength": 300}}}}, "facts_changed": {"type": "boolean", "enum": [false]}}}, "rules": ["facts_changed is always false.", "before_sha256 pins the page version the patch applies to."], "status": "proposal", "admission": "not_admitted", "content_kind": "authored_guidance", "license": "MIT", "provenance": {"source": "original ta-amps authored proposal", "license": "MIT", "generator": "scripts/build_packs.py", "independently_verified": false}, "dimensions": {"determinism": 0.0, "evidence_grounding": 0.0, "token_efficiency": 0.0, "safety_compliance": 0.0, "verification_tier": "unverified"}, "dimension_basis": {"measured": false, "method": "unmeasured_floor", "reason": "Tessera requires these axes, so each is set to its lowest value and the tier is unverified. No quality is claimed. Replace them only with measured values and the evidence that produced them."}, "relations": []}},
{"store": "seedpack.docs-improvement", "key": "docs-improvement.v0.1.0.template.example-run", "expected_version": 0, "producer_surface": "surface:tessera", "visibility_scope": "surface_only", "allowed_surfaces": [], "target_cohorts": ["all"], "tags": ["category:noun.eval_run", "pack:docs-improvement", "role:template", "content:authored", "spdx:MIT", "status:quarantined"], "value": {"category_id": "noun.eval_run", "role": "template", "pack": "docs-improvement", "pack_version": "0.1.0", "title": "Template: results of running every code block and checking every local link", "category_reason": "An example run is a deterministic check run.", "describes": "results of running every code block and checking every local link", "schema": {"type": "object", "additionalProperties": false, "required": ["blocks", "links"], "properties": {"blocks": {"type": "array", "minItems": 0, "maxItems": 200, "items": {"type": "object", "additionalProperties": false, "required": ["location", "language", "result", "output_excerpt"], "properties": {"location": {"type": "string", "minLength": 1, "maxLength": 300}, "language": {"type": "string", "minLength": 1, "maxLength": 40}, "result": {"type": "string", "enum": ["pass", "fail", "not_runnable"]}, "output_excerpt": {"type": "string", "minLength": 0, "maxLength": 600}}}}, "links": {"type": "array", "minItems": 0, "maxItems": 500, "items": {"type": "object", "additionalProperties": false, "required": ["location", "target", "result"], "properties": {"location": {"type": "string", "minLength": 1, "maxLength": 300}, "target": {"type": "string", "minLength": 1, "maxLength": 400}, "result": {"type": "string", "enum": ["ok", "broken", "not_checked"]}}}}}}, "rules": ["External links are not_checked unless network access was allowed."], "status": "proposal", "admission": "not_admitted", "content_kind": "authored_guidance", "license": "MIT", "provenance": {"source": "original ta-amps authored proposal", "license": "MIT", "generator": "scripts/build_packs.py", "independently_verified": false}, "dimensions": {"determinism": 0.0, "evidence_grounding": 0.0, "token_efficiency": 0.0, "safety_compliance": 0.0, "verification_tier": "unverified"}, "dimension_basis": {"measured": false, "method": "unmeasured_floor", "reason": "Tessera requires these axes, so each is set to its lowest value and the tier is unverified. No quality is claimed. Replace them only with measured values and the evidence that produced them."}, "relations": []}},
{"store": "seedpack.docs-improvement", "key": "docs-improvement.v0.1.0.template.review", "expected_version": 0, "producer_surface": "surface:tessera", "visibility_scope": "surface_only", "allowed_surfaces": [], "target_cohorts": ["all"], "tags": ["category:noun.eval_run", "pack:docs-improvement", "role:template", "content:authored", "spdx:MIT", "status:quarantined"], "value": {"category_id": "noun.eval_run", "role": "template", "pack": "docs-improvement", "pack_version": "0.1.0", "title": "Template: an independent review of a rewrite against the audit's issues", "category_reason": "A review is a verification run.", "describes": "an independent review of a rewrite against the audit's issues", "schema": {"type": "object", "additionalProperties": false, "required": ["checked", "verdict", "reasons"], "properties": {"checked": {"type": "array", "minItems": 1, "maxItems": 60, "items": {"type": "object", "additionalProperties": false, "required": ["issue_ref", "result"], "properties": {"issue_ref": {"type": "string", "minLength": 1, "maxLength": 300}, "result": {"type": "string", "enum": ["fixed", "not_fixed", "made_worse"]}, "note": {"type": "string", "minLength": 0, "maxLength": 300}}}}, "verdict": {"type": "string", "enum": ["accept", "revise", "reject"]}, "reasons": {"type": "array", "minItems": 1, "maxItems": 8, "items": {"type": "string", "minLength": 1, "maxLength": 300}}}}, "rules": ["The reviewer did not write the rewrite."], "status": "proposal", "admission": "not_admitted", "content_kind": "authored_guidance", "license": "MIT", "provenance": {"source": "original ta-amps authored proposal", "license": "MIT", "generator": "scripts/build_packs.py", "independently_verified": false}, "dimensions": {"determinism": 0.0, "evidence_grounding": 0.0, "token_efficiency": 0.0, "safety_compliance": 0.0, "verification_tier": "unverified"}, "dimension_basis": {"measured": false, "method": "unmeasured_floor", "reason": "Tessera requires these axes, so each is set to its lowest value and the tier is unverified. No quality is claimed. Replace them only with measured values and the evidence that produced them."}, "relations": []}}
]}