arwp-braidgraph

ARWP BraidGraph

Use this skill when the question is not merely what should the site change?, but why does a change exist, what evidence supports it, what depends on it, and what evidence is still missing?

Core rule

Do not create a second ad-hoc provenance graph in notes, issues or agent memory when a valid BraidGraph can represent the relationship.

The canonical chain is:

source → rule → recommendation → surface/repo-file → transform → verification → measurement

Keep the evidence classes distinct. A recommendation is not authorization, a planned transform is not a deployment, verification is not a Search/AI outcome, and an observed ranking/citation movement is not proof of causality.

Sources of truth

Read only what is needed:

• docs/BRAIDGRAPH.md;
• schema/braid-graph.schema.json;
• the target BraidGraph artifact;
• its referenced Adaptive Upgrade Graph and Transformation Bundle when deeper evidence is required;
• explicit Braid revision evidence for superseded source/rule history;
• Change Receipts / owner measurement evidence when those artifacts exist.

Do not infer missing source history, repository ownership, deployment state or owner metrics.

Workflow

1. Validate first. Reject invalid graphs, duplicate IDs, dangling edges or mismatched transformation lineage before reasoning from them.
2. Choose the question type.
   • explain for “why is this file/change/recommendation here?”;
   • impact for “what should be re-reviewed because this source/rule changed?”;
   • missing-evidence for “which transformations still lack implementation or outcome evidence?”
3. Trace recorded provenance only. If the graph does not contain the relationship, return it as unknown/unmapped rather than inventing an edge.
4. Preserve time. When explicit source/rule revision evidence exists, enrich the graph with prior version nodes and supersedes edges. Do not rewrite old nodes into the new truth.
5. Treat impact as a review queue. A changed rule can make downstream recommendations/transforms candidates for re-review; it does not automatically mean the implementation is broken or should be reverted.
6. Keep implementation and outcome separate. A passing build can close verification debt but cannot close ranking, AI citation, referral or business-outcome measurement debt.
7. Keep negative evidence. Negative, unchanged or mixed measurements stay attached to the graph and remain available for future learning.
8. Respect mutation gates. BraidGraph explains relationships; it never grants production authorization. Use the Target Transformation / Change Receipt controls for actual writes.
9. Escalate ownership gaps. If an exact rendered surface cannot be tied to an owning repository source, route that gap to Repository Mapper rather than guessing a file.
10. Report the smallest useful result. Return the affected nodes, exact provenance path, missing evidence class and required next review step; do not collapse the graph into a magic score.