Origin Doc Update

origin-doc-update

Treat docs/ as persistent AI context. Keep each fact in one layer only.

Do not copy implementation history into guides or current behavior into workstreams. Keep decision rationale in an ADR and link to it from the relevant spec, workstream/issue, or guide.

Start every task

1. Read docs/00_index.md if present.
2. Read the active workstream or issue.
3. Read only its related specs, guides, and ADRs when present.
4. Choose one work unit:
   • Use a workstream when multiple vertical-slice issues can run under the same authorization envelope until the same next human gate.
   • Use a standalone issue for one bounded change, an unrelated blocker, or work with an independent lifecycle.
   • Use docs only when no implementation changes.
5. Reuse the recorded branch or worktree. Do not create a second branch for resumed work.

Default to one workstream file with embedded issue blocks. Split it only when independent branches, parallel ownership, or file size makes one file materially harder to resume.

Create a workstream

Do not create the file immediately when the user asks for a workstream. First establish the human boundary.

1. Inspect the code and existing docs. Answer anything discoverable without asking the user.
2. Identify decisions that change authorization or the path of work.
3. Ask one question at a time, in dependency order, and include a recommended answer.
4. Confirm these items before writing the workstream:
   • goal, success criteria, and out-of-scope work;
   • actions the agent may take autonomously;
   • actions requiring confirmation, especially external writes, sends, submissions, deploys, destructive changes, data migrations, auth/secrets, dependencies, network access, and metered services;
   • cost or usage ceiling when metered work is possible;
   • test and quality gates;
   • merge policy: continuous delivery is the default — a PR whose recorded quality gates pass (CI when present, otherwise the recorded local gates) is merged autonomously. Record a human merge gate only as a named exception with its reason (e.g. live/production impact, spend, new dependencies); an unexplained merge gate silently kills autonomous runs downstream. The template's - Merge policy: line in the Authorization Envelope carries the choice;
   • the next human checkpoint and early stop conditions.
5. Classify runnability for every planned issue and fill its block's runnability: field: ready (completable with only current permissions and currently available information) or gated on <the human decision, missing input, or new permission>. Surface every gated point as a question now, during creation — a question asked here costs one interview turn, while the same question discovered mid-execution stops an entire autonomous run. As part of the same pass, judge whether each issue's acceptance is machine-verifiable (counts, thresholds, passing tests) or needs human review, and fill the - verify: line under its #### Acceptance: machine — <command and expected result> or human-review — <who reviews what>. Push subjective acceptance toward a quantifiable restatement; where human judgment is genuinely required, human-review records that the issue ends at a review gate — an agent cannot self-verify a subjective goal and will either stall or overclaim. These fields are not optional prose: validate_repo_docs.py rejects a missing or malformed value, because executors (origin-goal, origin-ws-loop) treat an unrecorded runnability as gated and stop the whole run at a gate nobody set.
6. State that origin-doc-update is pausing creation until these boundaries are confirmed.
7. After confirmation, create from references/workstream.template.md or run create_workstream.py with the confirmed boundary fields.

Record only decisions that are hard to reverse or surprising without context. Do not create ADRs for routine implementation choices, temporary investigation notes, or ordinary history already captured by the workstream/issue.

Do not audit or revoke IAM roles, API scopes, bucket bindings, or other session-granted access here. origin-permission-audit owns that lifecycle; origin-close-session invokes it before this skill when applicable and passes the verified outcome into the documentation slice.

Record an ADR

Use the repository-level docs/adrs/ directory for both kinds of decision:

• scope: spec — intent, requirements, architecture, design policy, security posture, or other decisions that change what the system is meant to be. Update the related docs/specs/ document with the current policy and link back to the ADR.
• scope: development — implementation, integration, migration, operational, dependency, or tooling tradeoffs made while delivering a workstream or issue. Link the ADR from that work unit and update a guide when the resulting behavior is user-, operator-, integrator-, or agent-visible.

Create the record when the decision is made, not only at session close. Use references/adr.template.md or scripts/create_adr.py <slug> --scope <spec|development> --status <proposed|accepted|rejected>. The generated filename is ADR-YYYYMMDD-<slug>.md. Keep accepted and rejected records in docs/adrs/; when a decision changes, create a new ADR and mark the old one superseded with a link instead of rewriting its decision history.

An ADR must state the context/problem, the decision, alternatives considered, consequences, and links to its source workstream/issue and affected specs/guides. Use status: proposed while a human gate is pending and status: accepted or rejected after the decision is settled. Record only the rationale here; current policy belongs in specs and current behavior belongs in guides.

Improvement issues

An improvement issue is a standalone issue in docs/issues/ that records a friction observation from development work — a stuck point, a repeated manual step, an inefficiency worth fixing later — rather than a requested change. Name it ISSUE-YYYYMMDD-improve-<slug> when the improvement targets the repository itself, and ISSUE-YYYYMMDD-improve-loop-<slug> when it targets the development-loop machinery (skills canonical under ~/.agents/skills/). The two scopes have different owners and approval paths, so the name must reveal the scope at a glance. Autonomous runs (e.g. origin-ws-loop) file observations here instead of interrupting their work; humans triage them later. Create with create_issue.py as usual.

Boundary with origin-trouble-log: an improvement issue is an actionable change request against this repository or the loop machinery. An observation about how the agent itself worked wrong — a silent no-op, a false completion report, a vacuous check, guidance friction — must ALSO be recorded as one origin-trouble-log entry, and when it is only an observation (no concrete change to implement yet) it goes ONLY there; a repo issue filed instead of a trouble entry is invisible to the cross-repo triage and was measured to get lost (2026-08-10 observation-filed-to-wrong-corpus).

Implement a workstream or issue

For each issue, complete one vertical slice:

1. Set guide_impact before implementation:

   • required: name every guide that must describe the resulting behavior.
   • none: write a concrete reason, such as internal refactor with unchanged behavior.

2. Define acceptance criteria and dependencies. The - verify: line under Acceptance is the executable form: run the recorded machine check, or route to the recorded reviewer.

3. Capture each qualifying decision in docs/adrs/ during the slice and link it from the issue/workstream. Mark a human-gated decision as proposed until the gate is resolved.

4. Implement and test, preferring red-green-refactor where practical.

5. Update the target guide in the same slice, before marking the issue complete.

6. Update current status and next actions. An issue's status must be exactly one of pending, in_progress, blocked, complete — validate_repo_docs.py rejects anything else, and plausible words like done are the usual way to find that out the hard way.

7. Continue automatically while inside the authorization envelope.

8. Stop at the next human gate or any recorded stop condition.

Never defer all guide work to workstream close. A guide is part of the definition of done for the issue that changed behavior.

Guide contract

Update or create a guide when behavior observable by a user, operator, integrator, or future agent changes, including:

• commands, configuration, schemas, APIs, supported workflows, and defaults;
• operational procedures, safety constraints, failure handling, and known limitations;
• behavior needed to use, maintain, debug, or extend the implementation correctly.

Do not update a guide for a pure internal refactor with identical behavior. Record guide_impact: none and why.

Write guides as current truth, not as a changelog. Include what the system does, how to use it, guarantees or constraints, maintenance/verification notes, and known limitations. Add the source workstream or issue ID in front matter.

Update specs and history

• Update a spec only when intent, requirements, architecture, or design policy changes.
• When that change follows a qualifying decision, update the related spec with the current policy and link the ADR; do not duplicate the full rationale in the spec.
• Keep chronological investigation and abandoned approaches in the active work unit, then archive it.
• Keep docs/00_index.md as links plus one-line routing descriptions. Do not add a second progress dashboard unless ordering across many workstreams cannot fit in the index.

Complete work

Before archive:

1. Verify every issue acceptance criterion.
2. Verify every issue has guide_impact: required or none.
3. Verify required guides describe the implemented behavior and reference the source work.
4. Verify qualifying decisions have an ADR in docs/adrs/, with a settled status or an explicit proposed human gate, and that related specs/guides/work units link to it.
5. Update specs if direction changed.
6. Reach the recorded human gate or record why the workstream stopped.
7. Run validate_repo_docs.py <repo path>. Name the repository rather than relying on the current directory: reached through an orchestrator, the current directory is a different repository, whose docs would validate clean and be reported as this one's result. Check the validated: line it prints.
8. Archive the work unit and update docs/00_index.md. The archive scripts accept an issue/ workstream id, .md filename, or path, stage the document/index changes before applying them, and roll back both files if a later replacement fails. They print the removal count plus the exact index lines they changed. Treat a zero or unexpected count as a stop condition and inspect the diff before continuing.
9. Hand merged branch cleanup to origin-git-cleanup.

Resume and onboard

When resuming, follow docs/00_index.md to the active work unit, reuse its branch, then continue from Next Actions without rescanning the repository.

When onboarding scattered docs, initialize the scaffold, classify each file by the ownership table, preserve history with git mv, confirm ambiguous removals, update cross-references, and validate.

Hooks

Keep hooks best-effort and non-blocking:

• session_start.sh may inject only docs/00_index.md.
• stop_nudge.sh may emit one short reminder when non-doc changes lack docs changes.
• Do not force-load this full skill from a hook and do not block commits or task completion from a semantic guess.

Use template fields and validate_repo_docs.py for deterministic enforcement. Hooks cannot reliably infer whether behavior changed and hard enforcement creates false positives and repeated token cost.

Resources

Templates in references/:

• 00_index.template.md
• workstream.template.md
• issue.template.md
• guide.template.md
• adr.template.md
• spec.template.md

Scripts in scripts/:

• init_repo_docs.py [repo]

• create_workstream.py <slug> --issue <slug> --scope <text> --confirmed-at YYYY-MM-DD --next-human-gate <name> --autonomous <text> --confirm-first <text> (--verify-machine <text> | --verify-human <text>) (--guide <GUIDE-id> | --no-guide-reason <text>) [--merge-policy <text>] [--gated-on <text>] [--repo <repo>] The interview's confirmed boundaries are required arguments: envelope (--autonomous, --confirm-first), acceptance (--verify-*), and — when the initial issue is not immediately runnable — --gated-on <reason>. A file created without them validates red, and executors treat the missing record as a gate.

• create_issue.py <slug> (--verify-machine <text> | --verify-human <text>) (--guide <GUIDE-id> | --no-guide-reason <text>) [--title <title>] [--repo <repo>] Pass a slug, not a full issue id — the ISSUE-<date>- prefix is added for you. The guide decision and the acceptance decision are required, as they are for create_workstream.py: name the guide this issue must update (or why not), and state how acceptance is verified. Without them the generated file cannot pass validate_repo_docs.py.

• create_adr.py <slug> --scope <spec|development> [--status <proposed|accepted|rejected>] [--title <title>] [--repo <repo>]

• archive_workstream.py <workstream> [--repo <repo>]

• archive_issue.py <issue> [--repo <repo>]

• archive_transaction.py: stage and atomically roll back archive/index file updates

• validate_repo_docs.py <repo> (prints the repository it validated)

  It also resolves every relative link under docs/**/*.md and fails on any that does not exist — archiving moves a file one level deeper and leaves its referrers behind, and that breakage is otherwise invisible until someone follows a link. Only inline code spans are excluded — write an unresolvable path as `[x](../placeholder.md)` and it is ignored. A link inside a fenced block or an HTML comment is reported: block-level parsing was tried and removed, because across 26 repositories using this convention it cost 5 loud false positives in 2 of them and never found a link the simpler rule misses, while repeatedly opening regions it never closed and silently deleting every link to the end of a document. A repository adopting the check with existing rot can record it as debt in docs/validator-link-baseline.txt (one path<TAB>target per line, preferring the target-scoped form); the list only shrinks, so an entry that is now resolvable is itself an error.

Read the matching template before creating a file manually. Keep legacy archives in place; promote useful current knowledge into a guide or spec instead of renaming history.