markdown-vault-mcp: Skill for Claude Code

Self-review

This skill is the local self-review a change gets before its diff becomes someone else's problem: before a reviewer reads it, before a hosted bot spends the maintainer's tokens on it, before a fix costs a public push. It produces a findings report, not a verdict. The self-review pre-push hook requires only that a review of the pushed commit is recorded, not that it found nothing; deterministic CI remains the only merge gate. What it asks instead is honest convergence: every finding you report gets fixed or explicitly justified, in writing, before the push.

The review confirms preparation; it rarely discovers. Every criterion below is derived from files already open to you — the rules files, the diff, the code's own comments, the git history — so a clean first pass over a diff you wrote carefully is the normal outcome, not a lucky one.

When to run

• Before gh pr create (or your agent's equivalent) on a fresh branch.
• Before flipping a draft PR to ready.
• Before any push that updates a branch with an open PR.
• On request, against any named PR, branch, or range.

Small diffs are cheap to review; "docs-only" and "obvious" diffs are where contradicted comments and rule violations hide. Run it anyway.

Select the range

Review the cumulative diff — the same one every post-push reviewer sees — never "since my last push".

1. Resolve the base ref, in this order of authority:
   • the base the invoker explicitly named — an explicit instruction beats recorded metadata (a stacked PR may need a comparison GitHub's recorded base does not give);
   • otherwise the PR's actual base branch, when a PR exists (gh pr view --json baseRefName);
   • only as fallback, derive it: the nearest of origin/<default>, origin/release/* and origin/integration/* by ancestry (the same derivation scripts/structural_gate.sh uses). Never assume main: a PR targeting release/X.Y or a stacked PR reviewed against the default branch sweeps in the base branch's whole divergence or misses the backport's scope. An integration/<epic> → main PR is the one exception to reviewing the whole range as new: every child was reviewed on its way into the integration branch. Review what those reviews could not see — the conflict resolutions in each merge of main (git log --remerge-diff --merges "origin/$BASE_REF..HEAD", git 2.36+), semantic conflicts with main, whether the children fit together and the docs describe the finished result, and the release impact (breaking markers, the Closes lines). docs/contribute/integration-branches.md covers the rebased case.
2. Compute and check the endpoints before reviewing: