miklschmidt/archboard / skills/archboard-pr
archboard-pr
VerifiedHelp agents and humans understand architectural changes and choose meaningful PR boundaries. Use when creating PRs, updating PRs, or writing PR bodies, and load it together with any other PR skill, such as pr.
Explain a pull request
Write one body with these sections:
- Summary: The problem and resulting behavior, with a picture for changed architectural meaning.
- Evidence: The behavior or source facts that demonstrate the result.
- Merge Danger: Reversibility, affected consumers, and the first source location to inspect.
This structure follows Matt Pocock's MIT-licensed pr skill.
Use it when another PR skill applies too.
Before architecture operations, load the archboard consumer skill.
It owns discovery, authoring, schemas, claims, comparison, retention, publication, and recovery recipes.
Select the evidence
Read git diff --find-renames <base>...HEAD from the merge base.
For a dependent PR, use its actual base branch.
Honor the requested delivery structure, including one integration PR across several modules.
Read splitting only when independent delivery helps and the user permits it.
Address the owning vault explicitly, including one in another repository.
Discover modules and states through model read and model proposals.
Use model footprint --base <base> --head <head> for bound source changes.
With a head, it reads the model at that head, from Git and with no checkout: the branch reading.
--state then names a proposal that the vault holds at that head, so a stack layer's own proposal and bindings decide what its commits are set against.
Its vaultRead field names the vault that it read.
Its unboundFiles lists the changed files that no module is bound to.
Read those files, and skipped or unavailable source, directly from the diff.
A footprint without a changed module shows only that the bound code it read is unchanged. Judge architectural change from the whole diff.
Choose the evidence that fits:
- Durable architecture changes: Use the existing model and a compact proposal.
- New or changed logic: Author it as a flow in the proposal, and render it with
model render --flow <id> --grammar flowchartso that its markers compare with the review base. When timing and call routing matter more than the logic, render the same flow with--grammar sequence. Both grammars draw the same steps. - Incidental flows or processes: Use a temporary model.
- Design-only changes: Follow design evidence.
- Unchanged architectural meaning: Use concise text or a code example.
For legacy authority, follow the consumer migration reference for inventory and preview. Never rewrite originals just to obtain a PR picture. Finish when every architectural change has an explanation tied to an identified model state or source evidence, and every flowchart and sequence chart in the body comes from a model flow. Never write a flowchart or sequence chart in Mermaid.
Prepare the proposal
Read the existing PR state comment before creating a proposal. Locate its stable ID through the catalogue. For a proposal that predates code, follow reconciliation. Each added module with a binding binds source that the diff adds. If the source exists at the base, model it in Current first, in a documentation layer below this PR. That documentation needs no proposal of its own. Use consumer authoring and comparison recipes, preserving source evidence, documents, and order.
Compare with the actual review base:
archboard model compare --state <proposal-id> --against <base-state-or-checkpoint> -C <checkout>
archboard model footprint --base <base-ref> --head <head-ref> --state <proposal-id> --against <base-state-or-checkpoint> -C <checkout>
archboard check code --state <proposal-id> -C <checkout>
If the head does not yet hold your proposal, add --model-at checkout to the footprint to read the vault on disk.
For a planning root, use its empty baseline and omit absent selectors.
Fix findings caused by the change and record unavailable evidence.
Commit tracked authored inputs with implementation.
While the proposal is a draft, add --fail-preexisting to the footprint. It exits 1 for each added module whose bound code the branch does not add.
Finish when proposal meaning matches implementation, comparison accounts for every changed subject, and the draft's footprint passes --fail-preexisting.
Prepare artifacts
Follow renders to choose and inspect exact pictures. For requested narration or interactions that need ordered explanation, follow walkthroughs. Before sharing checkpoint-dependent evidence, follow the consumer publication recipe. Use existing setup and sign-in authorization. If setup or publication is unavailable, provide completed artifacts and state the limit. Finish when each artifact's reading, inspection, and history availability are known.
Write the body
Keep visible prose brief and use repository domain terms. Use proposal and state names as the consumer authoring reference requires. Lead Summary with the concrete problem and resulting behavior. For videos and transcripts, follow the walkthrough reference. For upload, replacement, and posted-body inspection, follow posting.
Keep this comment and marked section for future updates:
<!-- archboard-pr:begin -->
<!-- archboard-pr model="<model-id>" state="<proposal-id>" checkpoint="<exact-checkpoint>" against="<base-state-or-checkpoint>" -->
## Summary
Requests now enter the queue before workers process them.

## Evidence
The request integration case passes with a queued request and a worker result.
## Merge Danger
A revert restores direct dispatch, but it drops any request still in the queue. Workers read the queued message through `QueuedRequest` in `src/queue/message.ts`, so a change to that format breaks them first.
<!-- archboard-pr:end -->
Omit unavailable optional comment fields.
The Archboard pull-request GitHub Action reads state from this marker and posts one text comment with the proposal, vault link and footprint.
For an external vault, add its portable repository identity as vault.
For temporary evidence, use <!-- archboard-pr temporary --> so later editors regenerate it from source.
Evidence states before and after when both exist. For new behavior, name the focused test or observed result. Visible changes require inspected visual evidence. Documentation requires source-contract and formatting evidence, without new prose tests. Merge Danger states whether reverting restores behavior and names irreversible external effects. Keep generation details and temporary limits in the handoff unless they affect review or reproduction.
Adopt in the implementing PR
Follow the consumer proposal completion recipe for authorization and adoption. After implementation, adopt on the PR branch before review so code and architecture merge together. Commit adopted inputs and update the state comment. If the vault lives in another repository, the adoption cannot merge with the code. Prepare it in a PR of the vault's repository, link each PR from the other's body, and ask the owner which merges first. For a temporary model, leave the repository's lifecycle unchanged.
If another proposal reached Current first, PROPOSAL_SUPERSEDED refuses adoption.
Do not force it: full replacement undoes the other adoption.
Create a new proposal on Current with the same name, summary, documents, and changes.
Before adoption, compare Current and the original each with the original's predecessor through model compare --state <id> --against <predecessor-id>.
A subject that both comparisons change is a conflict. Tell the owner, and adopt only after the owner decides.
Adopt that proposal, then shelve the original with a reason naming its replacement.
If default-branch code already implements the draft, tell the owner before adoption and obtain agreement.
For stopped work, follow the consumer shelving authorization rule and retain its reason and exact baseline.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 469k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 321k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 321k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 321k | Updated | Claude CodeCodex | Verified | Install |