diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 000000000..35e42b4de --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,414 @@ +# UET Agent Operating Guide + +This file is the root entrypoint for AI agents and collaborators working in this repository. + +It does not replace the project standards. It tells an agent where truth lives, how to work +without inflating claims, and how to stay useful inside the actual UET workflow. + +## Purpose + +Use this file to orient quickly before editing code, rewriting docs, auditing a topic, or +answering research questions. + +The repository already contains the full operating standard in +[`docs/topics/For Work/`](./docs/topics/For%20Work/). This guide is the short version for +day-to-day agent work. + +## Project reality + +- `docs/` is the main research codebase, documentation root, and GitHub Pages source. +- `docs/topics/` contains the numbered topic workspaces and the standards workspace. +- `docs/topics/For Work/` is the canonical operating manual for topic research work. +- `docs/meta/` and `docs/topics/README.md` are the preferred source of truth for current + topic status, readiness, and claim restraint. +- Many files under `Result/`, `_Logs/`, generated reports, and audit outputs are artifacts, + not the first place to make narrative decisions from memory. + +## Default working style + +This repository is often used for: + +- auditing what is still weak, unclear, overstated, missing, or not yet standardized +- answering learning-oriented questions about how the repo works +- improving credibility, structure, verification discipline, and research legibility +- conducting topic research using the standards already documented in `For Work` + +If the request is ambiguous, prefer: + +1. inspect local evidence first +2. identify gaps, risks, or unclear claims +3. improve structure or wording conservatively +4. avoid promoting status unless the evidence clearly supports it + +When work spans repeated repair passes, prefer a visible hardening loop: + +1. package or confirm the current sources +2. regenerate one stable verifier artifact +3. add or tighten one machine-readable blocker gate +4. update the local topic docs to match the new blocker boundary +5. record the pass in the topic update log +6. commit the coherent change before starting the next wave + +When the user wants faster progress across many topics, prefer improving the +workflow standard and update-log discipline before trying to push every topic +forward at once: + +1. tighten the operating rule in `docs/topics/For Work/` or this guide if the + same ambiguity is slowing multiple topics +2. make the next blocker state machine-readable in the local topic package +3. use one pilot topic to prove the updated workflow before rolling it out more + broadly + +Treat this as the default acceleration path when progress feels slow across +many topics. Shared workflow clarity should compound before topic count does. + +When the same blocker shape appears in several topics, treat that as a +workflow problem first and a topic problem second. Prefer this order: + +1. tighten the shared rule in `AGENTS.md` or `docs/topics/For Work/` +2. name the repeated blocker class in machine-readable language +3. require active topics of that class to expose the blocker in a gate, + manifest, or artifact field +4. prove the repaired method in one pilot topic +5. only then broaden the rollout + +This prevents repeated topic work from drifting into custom one-off habits. + +When progress feels slow because a topic keeps producing more prose than +closure, add structure before adding scope: + +1. identify the single controlling blocker that still decides the topic state +2. require that blocker to exist in a machine-readable gate, manifest, or + artifact field +3. require the local `UPDATE_LOG.md` to say what changed, what was rerun, and + what still controls the topic now +4. do not start the next blocker wave until the current controller is visible + in both artifact state and log state + +This is the default anti-drift rule for repeated hardening work. The aim is to +stop a topic from feeling busy while remaining ambiguous. + +When a collaborator asks for "overall progress" or "what changed lately," +prefer reconstructing status from current artifacts, manifests, and update logs +instead of giving a prose-memory summary. The goal is to make repo-wide status +readable without guessing. + +When the repository is moving across many topics at once, prefer a status-first +workflow before starting new edits: + +1. inspect `docs/topics/README.md` and relevant `docs/meta/` records +2. inspect the local topic `README.md`, `LIMITATIONS.md`, and `VERIFICATION_SPEC.md` +3. inspect the current verifier artifact and any machine-readable blocker gates +4. inspect the topic `UPDATE_LOG.md` when the work spans multiple waves +5. summarize the current blocker chain before proposing promotion, publication, or rewrite + +If these sources disagree, treat the latest stable verifier artifact and +machine-readable blocker gate as the controlling state for the current pass, +then repair documentation drift afterward. + +If a topic package does not yet expose its current blocker chain clearly enough +to answer a status question, the next useful action is usually to add or tighten +one machine-readable gate and record the wave in `UPDATE_LOG.md` before trying +to advance the claim. + +When progress reporting itself becomes difficult, treat that as a standards +defect. The next useful action is usually one of: + +1. tighten the local topic `UPDATE_LOG.md` +2. tighten the blocker wording in the latest artifact or manifest +3. update `AGENTS.md` or the relevant `For Work` standard so the same + confusion does not recur elsewhere + +If several topics look stalled at the same time, do not spread effort evenly by +default. Prefer this order: + +1. update the shared workflow rule that would remove repeated ambiguity +2. require status-first reconstruction and update-log discipline on active topics +3. prove the revised method on one pilot topic +4. only then expand the same pattern to adjacent topics + +This keeps acceleration real instead of cosmetic. + +## Start here + +Open these files first when you need repository-wide context: + +1. [`README.md`](./README.md) +2. [`CONTRIBUTING.md`](./CONTRIBUTING.md) +3. [`docs/topics/README.md`](./docs/topics/README.md) +4. [`docs/topics/For Work/00_README.md`](./docs/topics/For%20Work/00_README.md) + +Then choose the next standard by task. + +## Reading order by task + +### If the task is audit, cleanup, or credibility repair + +1. [`docs/topics/For Work/01_Project_Research_Constitution.md`](./docs/topics/For%20Work/01_Project_Research_Constitution.md) +2. [`docs/topics/For Work/03_AI_Usage_and_Governance.md`](./docs/topics/For%20Work/03_AI_Usage_and_Governance.md) +3. [`docs/topics/For Work/04_Claim_and_Evidence_Rubric.md`](./docs/topics/For%20Work/04_Claim_and_Evidence_Rubric.md) +4. [`docs/topics/For Work/02_Project_Workflow_and_Lifecycle.md`](./docs/topics/For%20Work/02_Project_Workflow_and_Lifecycle.md) +5. [`docs/topics/For Work/18_Research_Hardening_Workflow.md`](./docs/topics/For%20Work/18_Research_Hardening_Workflow.md) + +### If the task is topic building or refactoring + +1. [`docs/topics/For Work/02_Project_Workflow_and_Lifecycle.md`](./docs/topics/For%20Work/02_Project_Workflow_and_Lifecycle.md) +2. [`docs/topics/For Work/10_Topic_Architecture_5x5(+1).md`](./docs/topics/For%20Work/10_Topic_Architecture_5x5(+1).md) +3. the relevant standards in `11-18` + +### If the task is multi-wave hardening or progress reconstruction + +1. [`docs/topics/For Work/18_Research_Hardening_Workflow.md`](./docs/topics/For%20Work/18_Research_Hardening_Workflow.md) +2. [`docs/topics/For Work/24_TEMPLATE_UPDATE_LOG.md`](./docs/topics/For%20Work/24_TEMPLATE_UPDATE_LOG.md) +3. the local topic `README.md`, `LIMITATIONS.md`, and `VERIFICATION_SPEC.md` +4. the latest verifier artifact and any blocker manifests or gate JSON files + +### If the task is mainly question answering or learning support + +1. inspect the local files that already define the topic or workflow +2. answer from local evidence first, not memory +3. cite the exact file that acts as the current source of truth +4. say clearly when a conclusion is inference rather than an explicit repo statement + +### If the task is repeated hardening, unblock work, or reconstruct progress + +1. inspect the local topic package first +2. open [`docs/topics/For Work/18_Research_Hardening_Workflow.md`](./docs/topics/For%20Work/18_Research_Hardening_Workflow.md) +3. open [`docs/topics/For Work/24_TEMPLATE_UPDATE_LOG.md`](./docs/topics/For%20Work/24_TEMPLATE_UPDATE_LOG.md) +4. rebuild the current blocker chain from manifests, gates, and artifacts before changing prose + +## Non-negotiable rules + +- Do not let a topic outrun its evidence. +- Do not upgrade a fit into a prediction. +- Do not upgrade an internal rerun into external validation. +- Do not use hardcoded local paths when repository path helpers or relative structure should + be used. +- Do not hide important physics logic or derivation-critical behavior in vague helper code. +- Do not rewrite repository status using stale counts from older prose when canonical + metadata exists. +- Do not smooth uncertainty away just because a polished sentence sounds better. + +## Claim discipline + +Use conservative wording unless the repository clearly supports something stronger. + +Preferred wording includes: + +- `hypothesis` +- `proposal` +- `model` +- `derived relation` +- `reproduced internally` +- `passes current internal benchmark` +- `externally replicated` +- `peer-reviewed result` + +Treat words like `solved`, `verified`, `proved`, `exact`, and `production grade` as +restricted unless the relevant local evidence explicitly justifies them. + +For claim wording, defer to: + +- [`docs/topics/For Work/04_Claim_and_Evidence_Rubric.md`](./docs/topics/For%20Work/04_Claim_and_Evidence_Rubric.md) +- [`docs/UET_Documentation_Details/STANDARDS/documentation_style_guide.md`](./docs/UET_Documentation_Details/STANDARDS/documentation_style_guide.md) + +## When editing a topic + +Before changing a topic narrative, inspect the local topic package first. Prefer this order +when files exist: + +1. topic `README.md` +2. `METHOD.md` +3. `LIMITATIONS.md` +4. `VERIFICATION_SPEC.md` +5. relevant `FORMULA_AUDIT.md` +6. code, data, and result artifacts + +When editing, preserve the distinction between: + +- theory and benchmark behavior +- derivation and calibration +- internal evidence and external evidence +- exploratory concept work and core-credibility work + +## Verification mindset + +When asked to review or improve work, default to a verification-first mindset: + +- look for broken structure, missing provenance, unclear baselines, weak thresholds, missing + limitations, and inflated claims +- prefer explicit metrics and named artifacts over adjectives +- treat generated figures and logs as outputs that should be explained by scripts and inputs +- if a topic status is unclear, consult `docs/topics/README.md` and the metadata in + `docs/meta/` before summarizing it +- if a topic has gone through many waves, prefer reconstructing the state from the update log, + verifier artifact, and blocker gates together rather than from prose memory alone +- if a topic is moving through repeated repair passes, use the hardening workflow and keep an + update log so later reviewers can reconstruct what changed and why +- if a topic seems stuck for a long time, first classify the blocker as source, formula, + artifact, threshold, dependency, or claim-boundary related before deciding what to do next + +## Update-log discipline + +Use an `UPDATE_LOG.md` when: + +- a topic is going through multiple hardening waves +- a reader would otherwise need to reconstruct progress from diffs alone +- blocker wording changes over time and needs a durable trail +- a verifier is rerun repeatedly and the result needs short historical context + +The latest completed entry should make the next controlling blocker obvious to +a new reviewer without requiring diff reconstruction first. + +An update log should record: + +- what changed in that wave +- which verifier or audit was actually run +- which blocker narrowed or stayed controlling +- whether claim wording changed or stayed the same +- what exact next blocker remains +- what currently controls the topic-level state after that wave + +An update log should not: + +- replace artifact JSON as the canonical result +- replace manifests as the source of truth for provenance +- become a place for promises that were not implemented yet +- be backfilled with vague summaries that hide what really changed + +For active hardening topics, treat the update log as required once any of these +become true: + +- three or more distinct hardening waves have occurred +- the controlling blocker has changed wording more than once +- multiple collaborators would otherwise need git history to reconstruct state +- the topic is being used as a pilot for a workflow change + +When a topic is being hardened across many short waves, prefer one concise +entry per completed wave over batching several blocker changes into one large +retroactive summary. + +Recommended sequence for repeated waves: + +1. change artifact, manifest, gate, or verifier logic first +2. rerun the verifier only when the evidence-producing state changed +3. sync topic docs to the new blocker boundary +4. write one concise update-log entry +5. commit the scoped wave before starting the next one + +For repeated hardening, each completed log entry should make these three things +recoverable in under a minute: + +1. what exact artifact or gate changed +2. what exact blocker became narrower +3. what exact blocker now controls the next wave + +If an entry cannot answer those three questions, tighten the entry before +treating the wave as complete. + +When a repeated ambiguity appears across several topics, prefer updating +`AGENTS.md` or the relevant `docs/topics/For Work/` standard close to the same +time so the improved method becomes reusable rather than living only in one +topic's local fixes. + +For workflow-repair waves that change `AGENTS.md` or `docs/topics/For Work/`, +record the linkage explicitly in the affected pilot topic log once the pilot is +updated. That keeps standards work and topic work traceable as one method chain +instead of two unrelated edits. + +For repo-wide status requests, a good reconstruction order is: + +1. `docs/topics/README.md` and relevant `docs/meta/` records +2. the local topic package (`README.md`, `LIMITATIONS.md`, `VERIFICATION_SPEC.md`) +3. the latest stable verifier artifact +4. blocker manifests or gate JSON files +5. `UPDATE_LOG.md` for wave history and next-controller context + +For a fast repo-wide progress snapshot, prefer reporting this compact tuple for +each active topic: + +1. current tier or readiness label +2. current controlling blocker +3. latest stable verifier result +4. last completed hardening wave +5. publication status boundary + +If any topic cannot be summarized in that tuple from local evidence, the topic +still needs status-hardening work before more ambitious promotion claims. + +## Git workflow + +Use `git` actively so work does not sit uncommitted for too long. + +- check `git status` before editing so you know whether the tree is already dirty +- do not revert or overwrite unrelated user changes +- keep commits scoped to the files and task you actually touched +- prefer small, meaningful commits over one large end-of-session dump +- when a unit of work is stable, commit it instead of letting it linger +- if the repository already contains unrelated changes, stage only the intended files +- write commit messages that describe the real change plainly, especially for audits, + standards, verification, and claim-discipline work + +Suggested commit cadence: + +1. finish one coherent change +2. run the relevant quick verification or review pass +3. stage only the intended files +4. commit before starting the next distinct chunk + +For multi-wave hardening, a good unit is: + +1. one blocker narrowed +2. one manifest or gate added or tightened +3. one verifier rerun if the artifact schema changed +4. one short update-log entry +5. one scoped commit + +When a standards or workflow change is introduced to speed up future research, +capture it in `AGENTS.md` or `docs/topics/For Work/` close to the same time so +later waves do not depend on unwritten habits. + +When touching standards such as `docs/topics/For Work/` or `AGENTS.md`, prefer a +separate commit from topic-level research changes unless the standards update is +required to explain the same hardening wave. + +## Agent behavior expectations + +- Be useful for audits, critique, normalization, and learning support. +- Prefer local evidence over speculation. +- Keep summaries legible and restrained. +- If evidence is mixed, say so plainly. +- If you infer something, label it as an inference. +- If a file in `For Work` already governs the decision, follow it instead of inventing a new + rule. +- If a topic is stuck, aim to make the blocker narrower and more machine-readable before trying + to make the claim stronger. +- If several topics are stuck at once, prefer improving the shared workflow, + logging, or standards first so later topic work compounds instead of + repeating the same ambiguity. +- When asked for a repo-wide status summary, reconstruct it from standards, metadata, topic + docs, artifacts, and update logs in that order rather than relying on memory. + +## Quick routing + +- Claim sounds too strong: open + [`04_Claim_and_Evidence_Rubric.md`](./docs/topics/For%20Work/04_Claim_and_Evidence_Rubric.md) +- AI-generated wording needs review: open + [`03_AI_Usage_and_Governance.md`](./docs/topics/For%20Work/03_AI_Usage_and_Governance.md) +- Topic structure is messy: open + [`10_Topic_Architecture_5x5(+1).md`](./docs/topics/For%20Work/10_Topic_Architecture_5x5(+1).md) +- Data provenance is weak: open + [`12_Data_Standard.md`](./docs/topics/For%20Work/12_Data_Standard.md) +- Result artifacts are unclear: open + [`14_Result_Standard.md`](./docs/topics/For%20Work/14_Result_Standard.md) +- Formula origin or units are unclear: open + [`17_Formula_Audit_Standard.md`](./docs/topics/For%20Work/17_Formula_Audit_Standard.md) +- The topic is stuck in repeated `FAIL` or `WARN` cycles: open + [`18_Research_Hardening_Workflow.md`](./docs/topics/For%20Work/18_Research_Hardening_Workflow.md) +- You need a durable record of what changed across waves: open + [`24_TEMPLATE_UPDATE_LOG.md`](./docs/topics/For%20Work/24_TEMPLATE_UPDATE_LOG.md) + +## One-line principle + +Use the agent as a careful research assistant, auditor, and systems organizer, not as the +final authority that upgrades evidence by confidence alone. diff --git a/docs/topics/For Work/00_README.md b/docs/topics/For Work/00_README.md index f1f22f644..7190fc89e 100644 --- a/docs/topics/For Work/00_README.md +++ b/docs/topics/For Work/00_README.md @@ -51,7 +51,7 @@ flowchart TD ### If you are creating a new topic 1. [02_Project_Workflow_and_Lifecycle.md](./02_Project_Workflow_and_Lifecycle.md) -2. [10_Topic_Architecture_5x4.md](./10_Topic_Architecture_5x4.md) +2. [10_Topic_Architecture_5x5(+1).md](./10_Topic_Architecture_5x5(+1).md) 3. [11_Code_README_Standard.md](./11_Code_README_Standard.md) 4. [12_Data_Standard.md](./12_Data_Standard.md) 5. [13_Reference_Standard.md](./13_Reference_Standard.md) @@ -85,7 +85,7 @@ flowchart TD | `02_Project_Workflow_and_Lifecycle.md` | readiness and promotion workflow | you need to place a topic in the correct stage | | `03_AI_Usage_and_Governance.md` | human-AI collaboration rules | AI is drafting, refactoring, or auditing work | | `04_Claim_and_Evidence_Rubric.md` | wording and evidence control | a claim feels too strong or too vague | -| `10_Topic_Architecture_5x4.md` | folder architecture | you are laying out or repairing topic structure | +| `10_Topic_Architecture_5x5(+1).md` | folder architecture | you are laying out or repairing topic structure | | `11_Code_README_Standard.md` | code documentation standard | you are documenting runnable scripts | | `12_Data_Standard.md` | provenance and dataset control | a result depends on local or external data | | `13_Reference_Standard.md` | source and bibliography discipline | references need to constrain claims better | @@ -97,13 +97,20 @@ flowchart TD | `21_TEMPLATE_ANALYSIS.md` | analysis note template | creating structured technical analysis notes | | `22_UET_PAPER_TEMPLATE.tex` | manuscript starter | building a paper draft from a mature topic | | `23_TEMPLATE_FORMULA_AUDIT.md` | formula registry starter | starting a dedicated formula-audit file | +| `18_Research_Hardening_Workflow.md` | repeated repair workflow | narrowing a controlling blocker through auditable hardening waves | +| `24_TEMPLATE_UPDATE_LOG.md` | update log template | recording multi-wave progress without replacing artifacts | +| `25_Research_Throughput_Workflow.md` | token-saving hardening workflow | generating compact wave packets before reading whole topics | +| `26_AI_AGENT_SKILL_MAP.md` | AI skill layer map | deciding which UET-focused skill should support a task | +| `27_AI_AGENT_ROUTING_MATRIX.md` | AI task routing matrix | routing common user requests to the minimum useful skill set | +| `28_AI_AGENT_SKILL_AUTHORING_STANDARD.md` | UET skill authoring rules | creating or reviewing skills without replacing `For Work` | +| `29_TEMPLATE_AI_AGENT_SKILL_SPEC.md` | skill spec template | drafting a portable UET skill before installing it | ## Quick decision matrix | If the problem is... | Open first | Then open | | :-- | :-- | :-- | | claim sounds too strong | `04_Claim_and_Evidence_Rubric.md` | `01_Project_Research_Constitution.md` | -| topic structure is messy | `10_Topic_Architecture_5x4.md` | `02_Project_Workflow_and_Lifecycle.md` | +| topic structure is messy | `10_Topic_Architecture_5x5(+1).md` | `02_Project_Workflow_and_Lifecycle.md` | | code exists but nobody knows how to run it | `11_Code_README_Standard.md` | `14_Result_Standard.md` | | dataset source is unclear | `12_Data_Standard.md` | `04_Claim_and_Evidence_Rubric.md` | | references are decorative instead of useful | `13_Reference_Standard.md` | `15_Paper_Standard.md` | @@ -111,6 +118,11 @@ flowchart TD | formula exists but provenance is unclear | `17_Formula_Audit_Standard.md` | `11_Code_README_Standard.md` | | units or variable meanings are unclear | `17_Formula_Audit_Standard.md` | `02_Project_Workflow_and_Lifecycle.md` | | AI wrote smooth prose without derivation support | `03_AI_Usage_and_Governance.md` | `04_Claim_and_Evidence_Rubric.md` | +| topic is moving too slowly because blockers are vague | `18_Research_Hardening_Workflow.md` | `02_Project_Workflow_and_Lifecycle.md` | +| many changes happened and progress is hard to track | `24_TEMPLATE_UPDATE_LOG.md` | `18_Research_Hardening_Workflow.md` | +| repeated topic passes are consuming too many tokens | `25_Research_Throughput_Workflow.md` | `18_Research_Hardening_Workflow.md` | +| AI agent needs the right skill or workflow | `27_AI_AGENT_ROUTING_MATRIX.md` | `26_AI_AGENT_SKILL_MAP.md` | +| a new UET-specific Codex skill is being created | `28_AI_AGENT_SKILL_AUTHORING_STANDARD.md` | `29_TEMPLATE_AI_AGENT_SKILL_SPEC.md` | ## Naming pattern @@ -119,6 +131,10 @@ flowchart TD | `00-04` | governance and master rules | | `10-17` | operational standards by work pillar | | `20+` | templates and production assets | +| `18` | repeated hardening workflow | +| `24` | durable update-log template | +| `25` | throughput and token-saving workflow | +| `26-29` | AI skill routing, authoring, and portable skill specs | ## Compatibility map @@ -129,7 +145,7 @@ flowchart TD | `01_Project_Workflow_and_Lifecycle.md` | `02_Project_Workflow_and_Lifecycle.md` | | `02_AI_Usage_and_Governance.md` | `03_AI_Usage_and_Governance.md` | | `03_Claim_and_Evidence_Rubric.md` | `04_Claim_and_Evidence_Rubric.md` | -| `how to topics5x4.md` | `10_Topic_Architecture_5x4.md` | +| `how to topics5x4.md` | `10_Topic_Architecture_5x5(+1).md` | | `how to Code README.md` | `11_Code_README_Standard.md` | | `how to Data Standard.md` | `12_Data_Standard.md` | | `how to Reference Standard.md` | `13_Reference_Standard.md` | diff --git a/docs/topics/For Work/18_Research_Hardening_Workflow.md b/docs/topics/For Work/18_Research_Hardening_Workflow.md new file mode 100644 index 000000000..1bc860c0a --- /dev/null +++ b/docs/topics/For Work/18_Research_Hardening_Workflow.md @@ -0,0 +1,390 @@ +# Research Hardening Workflow + +This document defines the standard hardening workflow for moving a topic from +loosely organized research into an auditable package with explicit blockers. + +It is not a promotion rule by itself. It is the step-by-step operating method +used to make later readiness and claim decisions faster, clearer, and more +repeatable. + +## Purpose + +Provide a shared hardening sequence so collaborators do not rebuild audit logic +from scratch for every topic. + +Use this workflow to answer: + +- what should be done first +- what should be recorded at each step +- which artifacts turn ambiguity into named blockers +- how to keep progress visible without inflating claims + +## When to use + +Use this file when: + +- a topic feels stuck between draft and reproducible +- evidence exists but is scattered across code, notes, and artifacts +- a verifier is growing but claim boundaries are still vague +- you need to decide whether to deepen a topic or leave it source-ready +- multiple topics need the same audit pattern + +## Workflow summary + +```mermaid +flowchart TD + A["Source package"] --> B["Diagnostic artifact"] + B --> C["Hardening gates"] + C --> D["Predictive or mechanism candidate"] + D --> E["Claim and publication gate"] + A -. source gaps .-> A + C -. blocker found .-> B + E -. overclaim or missing dependency .-> C +``` + +## Core idea + +Hardening is the work of turning unclear progress into explicit, auditable state. + +The main outputs are not only better prose. The main outputs are: + +- source manifests +- hashes and local paths +- verifier artifacts +- blocker reasons +- dependency maps +- claim boundaries +- next required artifacts + +## Hardening stages + +| Stage | Main question | Required output | Typical blocker | +| :-- | :-- | :-- | :-- | +| `Source packaging` | do we know what inputs we are using? | source manifest, DOI or URL, local path, hash, units | source family unclear | +| `Diagnostic artifact` | can we rerun and inspect the current behavior? | verifier, metrics, thresholds, artifact JSON | no stable script or threshold | +| `Unit Audit` | do all formulas balance dimensionally? | unit closure status, explicit mathematical variable definitions | mismatched SI units, naked floats | +| `Hardening gate` | do we know why the topic is not ready? | machine-readable gate with blockers | vague or narrative-only status | +| `Predictive candidate` | what exact model or operator would count as progress? | parameter policy, split manifest, acceptance harness | fitted diagnostic mistaken for prediction | +| `Claim gate` | what may be said publicly right now? | claim class, blocked phrases, publication checks | README outruns artifact | + +## Standard sequence + +### 1. Package sources first + +Before adding stronger wording or new artifacts, record: + +- source identity +- DOI or URL +- local path +- file hash where practical +- preprocessing note +- unit basis +- benchmark role + +If a topic depends on a shared cache, record the exact shared path and why it is +used. + +### 2. Make one stable diagnostic artifact + +Before chasing broad theory claims, create one verifier that emits: + +- input identity +- metric names +- thresholds +- result status +- notes and limitations + +The first artifact may be diagnostic-only. That is acceptable as long as the +claim boundary says so clearly. + +### 3. Add hardening gates + +After the first artifact exists, add machine-readable gates for the main +blockers. Typical examples: + +- source readiness gate +- formula provenance gate +- unit closure gate (Dimensional analysis must perfectly balance) +- mathematical variable definition gate +- uncertainty readiness gate +- baseline comparator gate +- training or holdout split gate +- implementation provenance gate +- publication readiness gate + +The goal is not to produce many gates. The goal is to ensure each major blocker +has a named home, especially physical unit gaps. + +### 4. Separate diagnostics from candidate prediction + +If a topic may later claim prediction, explicitly separate: + +- calibration rows +- holdout rows +- external cross-check rows +- forbidden parameter sources +- accepted versus diagnostic parameter sets + +Do not let the current fitted diagnostic lane silently become the future +predictive lane. + +### 5. Define acceptance before implementation + +Before calling a model, operator, or mechanism "accepted", define: + +- required inputs +- required outputs +- parameter lock rules +- uncertainty rules +- residual-row schema if applicable +- baseline comparators +- blocked claims + +This is where acceptance harnesses and preflight manifests belong. + +### 6. Narrow blockers before broadening scope + +If a topic is blocked, try to change: + +- `missing` -> `evidence present but insufficient` +- `unclear blocker` -> `named blocker with required artifact` +- `broad readiness gap` -> `one preflight or provenance rule` + +This counts as real progress because it shortens the path to the next move. + +### 7. Upgrade public wording last + +Only after the previous stages are stable should README, analysis, or paper +language be upgraded. + +Hardening should usually change artifacts first, then documentation. + +## Standard hardening wave + +Use the following pattern for one hardening pass: + +1. pick one blocker that currently controls the topic-level state +2. decide whether the pass is a source pass, artifact pass, gate pass, or + claim-boundary pass +3. add or tighten the minimum manifest, gate, or verifier logic needed +4. rerun the relevant verifier only if the artifact-producing state changed +5. sync `README.md`, `LIMITATIONS.md`, `VERIFICATION_SPEC.md`, and + `FORMULA_AUDIT.md` if the boundary moved +6. write one update-log entry with the verifier result and the remaining blocker +7. commit the wave as one scoped unit + +This is the preferred way to speed up a difficult topic without losing audit +traceability. + +## Wave completion rule + +Do not treat a hardening wave as complete just because new prose or new files +exist. + +A wave is complete when all of these are true: + +1. the controlling blocker for that wave is narrower than before +2. the narrower blocker is visible in a machine-readable artifact, gate, or + manifest +3. topic docs reflect the new blocker boundary +4. the local `UPDATE_LOG.md` states what now controls the next wave + +If those four conditions are not met, the topic may be busier but it is not yet +harder in the research sense. + +## Status reconstruction before a wave + +Before choosing the next blocker, reconstruct the current topic state from +local evidence instead of prose memory. + +Use this order: + +1. root topic status sources such as `docs/topics/README.md` and relevant + `docs/meta/` records +2. local `README.md`, `LIMITATIONS.md`, and `VERIFICATION_SPEC.md` +3. latest verifier artifact +4. machine-readable blocker gates, manifests, and dependency records +5. local `UPDATE_LOG.md` when the topic has already gone through several waves + +If the sources disagree, do not average them together. Treat the latest stable +artifact and blocker gate wording as the controlling state for the current +pass, then bring documentation back into alignment. + +## Multi-topic hardening strategy + +When several topics are blocked at once, improve the shared workflow before +trying to deeply advance every topic in parallel. + +Use this order: + +1. identify the repeated ambiguity slowing several topics +2. tighten the shared rule in `For Work` or the repository guide +3. require one machine-readable blocker per active topic +4. prove the updated workflow in one pilot topic +5. roll the pattern out only after the pilot stays auditable + +This is the standard way to increase research throughput without weakening +claim discipline. + +If the same blocker wording or provenance ambiguity keeps reappearing, treat +that recurrence as a standards signal. The next useful move is often: + +1. tighten the shared rule in `AGENTS.md` or `For Work` +2. define the blocker class in machine-readable language +3. require one pilot topic to expose that blocker cleanly +4. only then spread the pattern more broadly + +This is how workflow repair becomes reusable instead of staying trapped inside +one topic. + +## Progress reconstruction rule + +When a collaborator asks why progress feels slow, answer from blocker +reconstruction first, not from file count, prose length, or time spent. + +Use this order: + +1. identify the current controlling blocker in the latest stable artifact or gate +2. identify whether the last wave narrowed that blocker or only added context +3. identify whether the local `UPDATE_LOG.md` makes the next controller explicit +4. only then decide whether the topic needs deeper research or shared workflow repair + +If a status question cannot be answered from that sequence in under a minute, +the topic still needs status-hardening work before more theory expansion. + +## What to optimize for + +In a difficult topic, the goal of a wave is usually one of these: + +- reduce ambiguity +- isolate the controlling blocker +- make the blocker reproducible +- stop a branch result from overclaiming for the whole topic +- prepare the next predictive or mechanism candidate cleanly + +Trying to solve every weakness in one pass usually slows the topic down. + +## Required hardening outputs + +Every topic being actively hardened should aim to maintain: + +- `README.md` +- `METHOD.md` +- `DATA_MANIFEST.md` +- `VERIFICATION_SPEC.md` +- `LIMITATIONS.md` +- `FORMULA_AUDIT.md` or equivalent +- at least one verification artifact in `Result/artifacts/` +- `UPDATE_LOG.md` once the topic enters repeated hardening waves + +## Wave packet rule + +For repeated hardening, treat one completed wave as a small packet with all of +these parts visible: + +1. one controlling blocker identified +2. one artifact, gate, or manifest tightened +3. one verifier rerun if evidence-producing state changed +4. one doc sync to the new blocker boundary +5. one update-log entry naming the next controller +6. one scoped commit + +If one of those parts is missing, the wave may still be useful, but it is not +yet closed as a standard hardening packet. +- at least one machine-readable blocker gate if the topic is not claim-ready + +Recommended additions for predictive or operator-like work: + +- parameter manifest +- parameter preflight or acceptance manifest +- training or holdout split manifest +- implementation provenance manifest +- publication readiness gate + +## Choosing where to stop + +Not every topic needs to become predictive or academic-ready immediately. + +A topic may stop intentionally at: + +- `Source-ready` + Source package exists but model work is deferred. +- `Diagnostic-only` + Verifier and artifact exist, but the lane is not prediction or validation. +- `Predictive-candidate-prep` + Acceptance harness, parameter policy, and split exist, but no accepted model exists yet. + +This is better than pretending every topic must progress to the same depth now. + +## Log discipline + +Hardening work should be visible across time. + +Use an update log when: + +- a topic is undergoing multiple waves of cleanup +- several manifests or gates are being added incrementally +- you want a human reader to understand what changed without diff-hunting + +The update log does not replace artifacts or manifests. + +Use the update log to record: + +- what changed +- what verifier or audit was run +- what blocker narrowed +- what still remains open +- whether the claim boundary changed or stayed the same + +Use [24_TEMPLATE_UPDATE_LOG.md](./24_TEMPLATE_UPDATE_LOG.md) as the standard +format. + +Minimum expectation for a multi-wave topic: + +- one entry per coherent hardening pass +- entries written after real work, not before +- verifier commands listed only when actually run +- blocker wording aligned with the artifact or gate wording +- the latest entry must make the next controlling blocker obvious to a new + reviewer + +## Anti-patterns + +Do not: + +- start with summary prose before source packaging +- treat one passing diagnostic threshold as external validation +- create blockers only in prose when a gate or manifest should exist +- add many bespoke manifests with no clear acceptance role +- use update logs as the only source of truth for status +- treat progress on one lane as if it upgrades the whole topic automatically + +## Review questions + +Before closing a hardening pass, ask: + +1. What ambiguity was removed? +2. Which blocker is now machine-readable? +3. Which artifact or manifest was added? +4. Did any public wording change without stronger evidence? +5. What exact next artifact would unlock the next step? + +## Key rules + +- source packaging comes before promotion language +- one stable artifact is better than many partial ones +- blockers should be narrowed, not hidden +- diagnostic lanes must stay labeled as diagnostic +- acceptance conditions should be written before implementation is promoted +- update logs support coordination, but artifacts remain the main evidence + +## Checklist + +- [ ] source package is explicit enough for audit +- [ ] at least one stable artifact exists +- [ ] current blockers are machine-readable where practical +- [ ] diagnostics and predictive candidates are not conflated +- [ ] acceptance conditions are defined before strong promotion +- [ ] claim language still matches current evidence +- [ ] update log is used if the hardening work spans multiple waves +- [ ] each wave leaves a narrower blocker or a clearer claim boundary than before diff --git a/docs/topics/For Work/24_TEMPLATE_UPDATE_LOG.md b/docs/topics/For Work/24_TEMPLATE_UPDATE_LOG.md new file mode 100644 index 000000000..0c18881ab --- /dev/null +++ b/docs/topics/For Work/24_TEMPLATE_UPDATE_LOG.md @@ -0,0 +1,92 @@ +# UPDATE LOG: [Topic Name or Workstream] + +> **Scope:** `[Topic path or standards workspace area]` +> **Owner:** `[Human, team, or AI collaborator]` +> **Purpose:** `[Why this log exists]` + +## When to use + +Use this log when a topic or standards area is being updated across multiple +passes and a reader needs a clean history of what changed, what was verified, +and what remains blocked. + +## Log rules + +- Log real work, not intentions alone. +- Record verifier or audit commands when they were actually run. +- Name blockers in the same language used by manifests or artifacts. +- Keep entries short and audit-friendly. +- Do not let this log replace canonical status in artifacts, manifests, or + README files. +- One entry should usually correspond to one coherent hardening wave. +- The latest completed entry should tell a new reviewer what the next + controlling blocker is without needing to inspect git history first. +- Each completed entry should make three things easy to recover: what changed, + what blocker narrowed, and what blocker now controls the next wave. +- Once a topic has entered repeated hardening, the update log should be + maintained continuously rather than recreated only when someone asks for a + summary. +- If the topic is serving as a pilot for a shared workflow change, note that + linkage in the relevant entry so standards work and topic work stay connected. + +## Recommended use in repeated waves + +When a topic is being hardened across many short passes, use this log as the +human reconstruction layer between artifacts and prose. + +Recommended pattern: + +1. artifact or gate changes first +2. rerun verifier when the evidence-producing state changed +3. sync topic docs to the new blocker boundary +4. write one concise log entry +5. commit the wave as a scoped unit + +Treat the latest completed entry as a status handoff. A reviewer should be able +to answer all of these from the top entry without opening git history first: + +1. what exact artifact, manifest, or gate changed +2. what exact blocker became narrower +3. what exact blocker now controls the next wave + +If the same ambiguity appears in several topics, update the shared workflow +standard near the same time and record that linkage briefly in the topic log. +That helps later reviewers understand whether the wave was topic-deepening work +or workflow-repair work. + +Do not backfill a long series of vague entries after the fact if the artifact +history can no longer support them clearly. + +## Entry template + +### [YYYY-MM-DD] - [Short title] + +- Scope: `[topic or file set]` +- Wave type: `[source pass / artifact pass / gate pass / claim-boundary pass / workflow-repair pass]` +- Added or changed: `[artifact, manifest, script, doc, or gate]` +- Files touched: `[key files only]` +- Verified with: `[command]` +- Result: `[PASS/WARN/FAIL or other concrete outcome]` +- Blocker narrowed: `[what became clearer]` +- Still open: `[next required artifact or unresolved blocker]` +- Next controller: `[what currently controls the topic-level state now]` +- Claim impact: `[no change / wording narrowed / wording upgraded with reason]` +- Workflow linkage: `[n/a or linked standards change / pilot topic note]` +- Notes: `[optional before/after metric, dependency effect, or why no rerun happened]` + +## Entries + +### [YYYY-MM-DD] - [Initial entry] + +- Scope: `[topic or file set]` +- Wave type: `[source pass / artifact pass / gate pass / claim-boundary pass / workflow-repair pass]` +- Added or changed: `[item]` +- Files touched: `[key files only]` +- Verified with: `[command or n/a]` +- Result: `[outcome]` +- Blocker narrowed: `[named blocker]` +- Still open: `[next step]` +- Next controller: `[current controlling blocker]` +- Claim impact: `[status]` +- Workflow linkage: `[n/a or linked standards change / pilot topic note]` +- Notes: `[optional detail]` diff --git a/docs/topics/For Work/25_Research_Throughput_Workflow.md b/docs/topics/For Work/25_Research_Throughput_Workflow.md new file mode 100644 index 000000000..f05ad9bcf --- /dev/null +++ b/docs/topics/For Work/25_Research_Throughput_Workflow.md @@ -0,0 +1,117 @@ +# Research Throughput Workflow + +This standard defines the token-saving workflow for repeated UET hardening work. + +It does not lower the evidence standard. It reduces repeated context reconstruction so AI +sessions spend more effort on physics, formulas, verifier behavior, and claim boundaries. + +## Purpose + +Use this workflow when progress feels slow because every topic pass requires rereading many +files before the actual blocker is clear. + +The goal is to turn the current audit state into a compact research wave packet before any +deep topic reading begins. + +## Core Rule + +Read the generated packet first. + +Do not open a whole topic folder if the packet already names the controlling blocker, the +recommended files, and the stop condition. + +## Standard Sequence + +1. Generate the current packet queue. + +```powershell +.venv\Scripts\python.exe docs\scripts\audit\audit_core_research_hardening.py --json --top 5 +``` + +2. Pick the first topic unless the user names a topic. + +3. Read only the files listed in that topic packet. + +4. Complete one hardening wave for one blocker. + +5. Stop when the packet stop condition is satisfied. + +6. Rerun the relevant verifier or audit only when the evidence-producing state changed. + +7. Record the wave in the topic `UPDATE_LOG.md` when the work spans repeated passes. + +## Single-Topic Packet + +Use this command when a user names a specific topic or when an agent needs a compact handoff: + +```powershell +.venv\Scripts\python.exe docs\scripts\audit\audit_core_research_hardening.py --topic 0.4_Superconductivity_Superfluids --emit-packets +``` + +The packet should be enough to answer: + +- what currently blocks the topic +- which files should be opened first +- which verifier command or artifact matters +- what one next action is allowed +- when the wave should stop + +## What To Automate + +Use scripts for: + +- queue ordering +- status summaries +- template or checklist generation +- repeated artifact inventory +- stale-priority detection +- JSON packet generation + +Use AI reasoning for: + +- physics interpretation +- formula provenance and unit analysis +- model failure diagnosis +- threshold and baseline meaning +- claim class and limitation wording + +## Wave Scope + +One wave should narrow one blocker. + +Do not combine data provenance repair, verifier repair, formula audit review, and public +wording upgrades unless they are required to close the same named blocker. + +If a topic has several blockers, pick the one named by the latest packet or the latest stable +machine-readable artifact. + +## Future-Concept Rule + +Do not spend throughput budget on `0.27+` future-concept topics in this phase unless the user +explicitly names one. + +Future-concept topics remain exploratory until a separate standards pass adds real data +provenance, runnable verification, formula audit coverage, and limitations. + +## Token-Saving Reading Rule + +Default reading order for a packet-driven pass: + +1. `docs/meta/core_research_next_actions.json` +2. the selected packet's recommended files +3. the latest verifier artifact named by the packet +4. `UPDATE_LOG.md` only if the topic has repeated waves +5. broader topic docs only if the blocker cannot be understood from the packet files + +This keeps hardening auditable without paying the full topic-reading cost every turn. + +## Completion Check + +A throughput-focused wave is complete when: + +- the controlling blocker is narrower than before +- the narrower blocker is visible in an artifact, manifest, gate, or topic doc +- the relevant packet stop condition is satisfied +- claim wording did not get stronger without stronger evidence +- the next packet or update-log entry makes the next controller clear + diff --git a/docs/topics/For Work/26_AI_AGENT_SKILL_MAP.md b/docs/topics/For Work/26_AI_AGENT_SKILL_MAP.md new file mode 100644 index 000000000..8e4f3d631 --- /dev/null +++ b/docs/topics/For Work/26_AI_AGENT_SKILL_MAP.md @@ -0,0 +1,142 @@ +# AI Agent Skill Map + +This file defines the UET skill layer for AI collaborators. + +It does not replace the standards in this folder. The skill layer is an adapter +that routes an agent to the right source files, reconstruction order, and output +discipline before it edits, audits, or summarizes topic work. + +## Purpose + +Use this map when: + +- creating or updating a UET-focused Codex skill +- deciding which skill should handle a repo task +- checking that AI workflow support still points back to canonical standards +- preventing repeated hardening work from becoming custom one-off behavior + +## Source-of-truth rule + +`docs/topics/For Work/` remains the canonical operating manual. + +Skills may: + +- route an agent to the right standard +- enforce reading order and checklist discipline +- produce draft audits, summaries, templates, and next-wave plans +- identify drift between docs, metadata, gates, artifacts, and logs + +Skills may not: + +- override a `For Work` standard +- promote readiness or claim status without human review +- treat prose memory as stronger than artifacts, manifests, gates, or metadata +- replace artifacts, manifests, or update logs as evidence records + +## Global required reads + +Every UET skill must start from these repo-local sources when they exist: + +1. `AGENTS.md` +2. `docs/topics/For Work/00_README.md` +3. `docs/topics/For Work/01_Project_Research_Constitution.md` +4. `docs/topics/For Work/03_AI_Usage_and_Governance.md` + +Then read the task-specific standards listed below. + +## Skill catalog + +| Skill | Use when | Required task-specific reads | Primary output | +| :-- | :-- | :-- | :-- | +| `uet-status-reconstructor` | reconstructing a topic's current state | `02_Project_Workflow_and_Lifecycle.md`, `18_Research_Hardening_Workflow.md`, topic docs, latest artifact/gate/log | status tuple and controlling blocker | +| `uet-repo-wide-progress-snapshot` | summarizing many topics | `02_Project_Workflow_and_Lifecycle.md`, `18_Research_Hardening_Workflow.md`, `docs/topics/README.md`, `docs/meta/` | compact topic table | +| `uet-claim-auditor` | reviewing claim wording or status language | `04_Claim_and_Evidence_Rubric.md`, style guide if available | claim/evidence map and flagged wording | +| `uet-hardening-wave` | planning or executing one blocker-narrowing pass | `18_Research_Hardening_Workflow.md`, `24_TEMPLATE_UPDATE_LOG.md` | one scoped wave packet | +| `uet-update-log-writer` | recording repeated hardening work | `24_TEMPLATE_UPDATE_LOG.md`, `18_Research_Hardening_Workflow.md` | concise update-log entry | +| `uet-formula-audit` | reviewing formulas, units, constants, or derivation status | `17_Formula_Audit_Standard.md`, topic `FORMULA_AUDIT.md` | formula audit findings | +| `uet-data-provenance-audit` | checking data source and local input traceability | `12_Data_Standard.md`, topic `DATA_MANIFEST.md` | provenance findings | +| `uet-result-artifact-reviewer` | reviewing result files or verifier artifacts | `14_Result_Standard.md`, topic `VERIFICATION_SPEC.md` | artifact quality findings | +| `uet-standards-drift-detector` | checking disagreement across docs, metadata, artifacts, gates, and logs | `02_Project_Workflow_and_Lifecycle.md`, `18_Research_Hardening_Workflow.md` | drift report and controlling state | + +## Skill specifications + +### `uet-status-reconstructor` + +- Purpose: rebuild a topic's current state from local evidence. +- Trigger: user asks for status, current blocker, readiness, what changed, or whether a topic can be promoted. +- Required reads: global required reads, `02_Project_Workflow_and_Lifecycle.md`, `18_Research_Hardening_Workflow.md`, `docs/topics/README.md`, relevant `docs/meta/`, topic `README.md`, `LIMITATIONS.md`, `VERIFICATION_SPEC.md`, latest artifact/gate, and `UPDATE_LOG.md` when present. +- Workflow: read canonical status sources first, read topic docs, read artifacts/gates, read log last for wave history, then report explicit facts separately from inference. +- Output: readiness label, controlling blocker, latest verifier result, last completed wave, publication boundary, and drift notes. +- Stop condition: if no artifact/gate/log can support a status claim, report that status-hardening is needed instead of guessing. + +### `uet-repo-wide-progress-snapshot` + +- Purpose: produce a compact multi-topic progress view. +- Trigger: user asks for overall progress, what changed lately, stalled topics, or active topic state. +- Required reads: global required reads, `docs/topics/README.md`, relevant `docs/meta/`, and the local package for each topic included. +- Workflow: summarize each topic with the same tuple so missing evidence is visible. +- Output: topic, readiness, controlling blocker, latest verifier result, last wave, publication boundary. +- Stop condition: if a topic cannot be summarized from local evidence, mark it as needing status-hardening. + +### `uet-claim-auditor` + +- Purpose: prevent claim inflation in topic docs and summaries. +- Trigger: user asks whether wording is too strong, requests a README rewrite, asks for publication language, or uses restricted phrases such as `proved`, `verified`, `solved`, `exact`, or `production grade`. +- Required reads: global required reads and `04_Claim_and_Evidence_Rubric.md`. +- Workflow: classify each major claim, map it to evidence/script/data/baseline, flag forbidden upgrades, and propose conservative replacements. +- Output: claim class, supporting evidence, allowed wording, flagged wording, and replacement language. +- Stop condition: if evidence cannot be located, keep the claim at hypothesis/model wording. + +### `uet-hardening-wave` + +- Purpose: run or plan one coherent blocker-narrowing wave. +- Trigger: user asks to harden, unblock, repair, or continue a repeated topic pass. +- Required reads: global required reads, `18_Research_Hardening_Workflow.md`, `24_TEMPLATE_UPDATE_LOG.md`, and the local topic package. +- Workflow: reconstruct state, choose one controlling blocker, decide wave type, tighten the smallest artifact/gate/manifest/doc boundary, rerun only relevant verifiers, sync docs, write log, and keep commit scope coherent. +- Output: wave packet with blocker, files, verifier decision, doc sync, log entry, and commit scope. +- Stop condition: if the blocker is not visible in a machine-readable artifact, gate, or manifest, make that visibility the next wave goal. + +### `uet-update-log-writer` + +- Purpose: make multi-wave work reconstructable without git archaeology. +- Trigger: user asks to record a hardening pass, update a topic log, or summarize a completed wave. +- Required reads: global required reads, `24_TEMPLATE_UPDATE_LOG.md`, and relevant artifact/gate/verifier output. +- Workflow: confirm real work happened, use artifact/gate wording for blockers, record verifier commands only if run, and keep the entry concise. +- Output: one update-log entry with scope, wave type, changed item, verification, result, narrowed blocker, next controller, claim impact, and workflow linkage. +- Stop condition: do not write a promise-only entry as if it were completed work. + +### `uet-formula-audit` + +- Purpose: audit formula provenance, units, constants, proof status, and code linkage. +- Trigger: user asks about equations, units, derivations, formula readiness, hidden constants, or physics/math credibility. +- Required reads: global required reads, `17_Formula_Audit_Standard.md`, topic `FORMULA_AUDIT.md`, `METHOD.md`, verifier code, and artifacts where relevant. +- Workflow: list important formulas, map variables and units, classify constant origins, assign proof status, identify failure modes, and compare README wording to formula status. +- Output: formula findings with required field gaps and next hardening step. +- Stop condition: if unit closure or origin is missing, keep wording at open/heuristic/checked-local status. + +### `uet-data-provenance-audit` + +- Purpose: ensure important datasets are traceable and honestly labeled. +- Trigger: user asks about data provenance, source readiness, manifests, dataset hashes, or reproducibility inputs. +- Required reads: global required reads, `12_Data_Standard.md`, topic `DATA_MANIFEST.md`, data files, scripts, and artifacts. +- Workflow: identify source, DOI/URL, license/terms, original filename, local path, preprocessing, unit convention, benchmark role, and artifact linkage. +- Output: missing provenance fields, mislabeled local copies, unit risks, and required manifest updates. +- Stop condition: if upstream identity or local path is unclear, block stronger reproducibility claims. + +### `uet-result-artifact-reviewer` + +- Purpose: review whether outputs are evidence products rather than storage clutter. +- Trigger: user asks about results, verifier JSON, figures, logs, artifacts, thresholds, or pass/fail records. +- Required reads: global required reads, `14_Result_Standard.md`, topic `VERIFICATION_SPEC.md`, result artifacts, verifier scripts, and inputs where practical. +- Workflow: classify outputs, confirm correct folder role, inspect artifact metadata, check metrics/thresholds/config/input identity, and separate logs from evidence. +- Output: artifact quality report and required metadata fixes. +- Stop condition: if evidence exists only in logs/screenshots, do not treat it as benchmark-grade. + +### `uet-standards-drift-detector` + +- Purpose: find disagreements between repo-wide status, local docs, artifacts, gates, and logs. +- Trigger: user asks why status is confusing, whether docs are stale, or whether a topic's narrative matches its evidence. +- Required reads: global required reads, `02_Project_Workflow_and_Lifecycle.md`, `18_Research_Hardening_Workflow.md`, repo-wide metadata, local topic docs, latest artifact/gate, and `UPDATE_LOG.md`. +- Workflow: compare sources in controlling order, identify the latest stable artifact/gate, list docs that outrun or understate it, and propose a sync-only repair. +- Output: drift table, controlling state, and repair order. +- Stop condition: if sources disagree, do not average them; name the controlling artifact/gate and mark the rest as drift. diff --git a/docs/topics/For Work/27_AI_AGENT_ROUTING_MATRIX.md b/docs/topics/For Work/27_AI_AGENT_ROUTING_MATRIX.md new file mode 100644 index 000000000..2f8b73760 --- /dev/null +++ b/docs/topics/For Work/27_AI_AGENT_ROUTING_MATRIX.md @@ -0,0 +1,57 @@ +# AI Agent Routing Matrix + +This file routes common UET work requests to the minimum useful skill set and +the canonical standards that must be read first. + +Use the task type, not the agent's preference, to choose a skill. + +## Routing table + +| User request shape | Primary skill | Companion skill | Must read before acting | +| :-- | :-- | :-- | :-- | +| "What is the current status?" | `uet-status-reconstructor` | `uet-standards-drift-detector` | `02_Project_Workflow_and_Lifecycle.md`, `18_Research_Hardening_Workflow.md` | +| "Give me overall progress" | `uet-repo-wide-progress-snapshot` | `uet-status-reconstructor` | `docs/topics/README.md`, relevant `docs/meta/` | +| "Continue hardening this topic" | `uet-hardening-wave` | `uet-update-log-writer` | `18_Research_Hardening_Workflow.md`, `24_TEMPLATE_UPDATE_LOG.md` | +| "This wording sounds too strong" | `uet-claim-auditor` | none | `04_Claim_and_Evidence_Rubric.md` | +| "Can this be promoted?" | `uet-status-reconstructor` | `uet-claim-auditor` | `01_Project_Research_Constitution.md`, `02_Project_Workflow_and_Lifecycle.md`, `04_Claim_and_Evidence_Rubric.md` | +| "Audit formulas or units" | `uet-formula-audit` | `uet-claim-auditor` | `17_Formula_Audit_Standard.md` | +| "Check data provenance" | `uet-data-provenance-audit` | `uet-result-artifact-reviewer` | `12_Data_Standard.md` | +| "Review result artifacts" | `uet-result-artifact-reviewer` | `uet-status-reconstructor` | `14_Result_Standard.md`, topic `VERIFICATION_SPEC.md` | +| "Docs and artifacts disagree" | `uet-standards-drift-detector` | `uet-status-reconstructor` | `02_Project_Workflow_and_Lifecycle.md`, `18_Research_Hardening_Workflow.md` | +| "Write/update an update log" | `uet-update-log-writer` | `uet-hardening-wave` | `24_TEMPLATE_UPDATE_LOG.md` | +| "Create or repair a topic structure" | `uet-hardening-wave` | `uet-data-provenance-audit` | `10_Topic_Architecture_5x5(+1).md`, `02_Project_Workflow_and_Lifecycle.md` | + +## Default reconstruction order + +When a task asks for status, promotion, progress, or blockers, use this order: + +1. `docs/topics/README.md` and relevant `docs/meta/` +2. local topic `README.md`, `LIMITATIONS.md`, and `VERIFICATION_SPEC.md` +3. latest verifier artifact and machine-readable blocker gates +4. manifests such as `DATA_MANIFEST.md` and `FORMULA_AUDIT.md` +5. `UPDATE_LOG.md` for wave history and next-controller context + +If these disagree, treat the latest stable artifact and gate as the controlling +state for the current pass, then repair documentation drift. + +## Decision rules + +- Use the narrowest skill that covers the task. +- Add a companion skill only when it protects a real boundary, such as claim + wording during status work or update-log discipline during hardening. +- Do not use a skill to skip reading the relevant standard. +- If the same blocker appears across several topics, route first to workflow + repair in `For Work`, then pilot one topic before broad rollout. +- If a topic lacks machine-readable blocker state, route to status-hardening + before promotion or publication work. + +## Examples + +| Prompt | Route | +| :-- | :-- | +| "Why is 0.11 still blocked?" | `uet-status-reconstructor` then `uet-standards-drift-detector` if docs disagree | +| "Make this README less overclaimed" | `uet-claim-auditor` | +| "Run another cleanup wave" | `uet-hardening-wave` and `uet-update-log-writer` | +| "Does this result JSON prove the topic?" | `uet-result-artifact-reviewer` and `uet-claim-auditor` | +| "Find missing formula provenance" | `uet-formula-audit` | +| "Summarize all active topics" | `uet-repo-wide-progress-snapshot` | diff --git a/docs/topics/For Work/28_AI_AGENT_SKILL_AUTHORING_STANDARD.md b/docs/topics/For Work/28_AI_AGENT_SKILL_AUTHORING_STANDARD.md new file mode 100644 index 000000000..375fdbaa8 --- /dev/null +++ b/docs/topics/For Work/28_AI_AGENT_SKILL_AUTHORING_STANDARD.md @@ -0,0 +1,102 @@ +# AI Agent Skill Authoring Standard + +This file defines how to create UET-specific Codex skills without duplicating or +weakening the repository standards. + +## Purpose + +Use this standard when creating, updating, reviewing, or installing skills that +support UET topic work. + +## Authoring principle + +A UET skill is an adapter over the standards, not a new standard. + +Keep skill instructions concise. Put stable governance in `For Work`; put only +triggering, reading order, workflow guardrails, and output expectations in the +skill. + +## Required skill shape + +Every UET skill must include: + +- a lowercase hyphenated name, preferably beginning with `uet-` +- frontmatter with only `name` and `description` +- a description that states when the skill should trigger +- a short body with required reads, workflow, outputs, and stop conditions +- repo-relative paths, not hardcoded local absolute paths +- explicit reminder that `For Work` is canonical + +## Required behavior + +Every UET skill must: + +1. read local evidence before summarizing, editing, or planning +2. use canonical metadata when present +3. keep hypothesis, model, benchmark, replication, and peer-review layers separate +4. keep diagnostic lanes separate from predictive lanes +5. preserve limitations and failure states +6. label inference separately from explicit repo statements +7. avoid readiness upgrades unless the user explicitly supplies human review + +## Forbidden behavior + +A UET skill must not: + +- promote a topic to a higher readiness label on its own +- convert internal benchmark results into external validation +- turn a fitted result into a prediction +- treat update logs as replacements for artifacts, manifests, or gates +- treat logs, screenshots, or showcase media as benchmark-grade evidence +- hide missing formula origins, unit closure gaps, or source provenance gaps +- create a custom workflow when a `For Work` standard already covers the case + +## Skill body template + +```markdown +--- +name: uet-example-skill +description: One-sentence capability and precise trigger contexts. +--- + +# UET Example Skill + +This skill is an adapter over `docs/topics/For Work/`; it is not a source of +truth. + +## Required reads + +1. `AGENTS.md` +2. `docs/topics/For Work/00_README.md` +3. task-specific standards +4. local topic evidence files + +## Workflow + +1. Reconstruct local evidence. +2. Apply the relevant `For Work` checklist. +3. Separate explicit evidence from inference. +4. Produce only the requested output. + +## Output + +- concise audit, plan, log entry, or status tuple +- controlling blocker where relevant +- unresolved gaps and stop conditions + +## Stop conditions + +- If evidence is missing, report the missing evidence rather than strengthening + the claim. +- If docs and artifacts disagree, name the controlling artifact or gate and + mark the rest as drift. +``` + +## Review checklist + +- [ ] skill points to the current file names in `For Work` +- [ ] skill does not duplicate long standards text +- [ ] skill has clear trigger language in frontmatter +- [ ] skill has a stop condition for missing evidence +- [ ] skill preserves the artifact/gate/log hierarchy +- [ ] skill can be validated with a realistic prompt diff --git a/docs/topics/For Work/29_TEMPLATE_AI_AGENT_SKILL_SPEC.md b/docs/topics/For Work/29_TEMPLATE_AI_AGENT_SKILL_SPEC.md new file mode 100644 index 000000000..f728b9a23 --- /dev/null +++ b/docs/topics/For Work/29_TEMPLATE_AI_AGENT_SKILL_SPEC.md @@ -0,0 +1,53 @@ +# TEMPLATE: AI Agent Skill Spec + +Use this template before creating or revising a UET-specific Codex skill. + +## Skill name + +`uet-[short-action-name]` + +## Purpose + +What this skill helps an agent do. + +## Trigger + +What a user might ask that should activate the skill. + +## Canonical standards + +- `AGENTS.md` +- `docs/topics/For Work/00_README.md` +- `[task-specific standard]` + +## Required local evidence + +- `[repo-wide metadata if relevant]` +- `[topic README / LIMITATIONS / VERIFICATION_SPEC]` +- `[artifact / gate / manifest / update log]` + +## Workflow + +1. `[first evidence-gathering step]` +2. `[standard checklist step]` +3. `[output shaping step]` + +## Allowed outputs + +- `[audit finding / status tuple / log entry / wave plan]` + +## Stop conditions + +- `[missing evidence condition]` +- `[claim/status boundary condition]` + +## Anti-overclaim rules + +- Do not promote readiness status without human review. +- Do not upgrade internal benchmark evidence into external validation. +- Do not replace artifacts, manifests, gates, or canonical metadata with prose. + +## Validation prompts + +- `[realistic prompt 1]` +- `[realistic prompt 2]`