docs(skills): clarify failed-run diagnostics and guard repairs (#18865)

## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work.
> - The failed-run skill guides agents from evidence through a tested
repair.
> - A review of repeated investigations found two small guidance gaps.
> - The skill does not link the existing bounded diagnostics reference.
> - Guard repairs can add qualification steps before identifying what
the guard protects.
> - This proposal adds the reference and makes that safety purpose
explicit.

## Linked Issues or Issue Description

**Where is the issue?**

`.agents/skills/fix-failed-paperclip-run/SKILL.md`, sections 1 and 4.

**What's wrong?**

Agents have to rediscover the authorized run, event, log, and recovery
reads. When a compatibility guard blocks progress, they can also add
qualification machinery even when runtime checks already establish
compatibility.

**Suggested fix**

Link the existing diagnostics reference. Require the agent to name the
guard's invariant, remove redundant prerequisites only when existing
runtime checks establish compatibility, and retain authority and
integrity checks.

Related: #16830 introduced this skill. #18066 is a concrete example of
removing a redundant saved-qualification prerequisite while keeping
runtime checks. #18602 proposes a separate CI-disposition skill and does
not contain these edits.

Refs #18861, #18862, #18863. Those issues track structural reliability
and review improvements from the same retrospective. This small skill
proposal does not close them.

## What Changed

- Link `skills/paperclip/references/run-diagnostics.md` from incident
discovery.
- Require a named invariant before changing a failing guard, and prefer
existing runtime compatibility checks over redundant qualification
steps.

## Verification

- The installed `skill-creator/scripts/quick_validate.py` validator
passes for the changed skill. Its PyYAML dependency ran in an isolated
temporary environment after the default Python lacked it.
- Both relative Markdown links resolve from the skill directory.
- Skill metadata is unchanged. The diff contains one file and seven
added lines.
- `git diff --check` passes.
- Full workspace typecheck, tests, and build were not run for this
documentation-only review proposal. Greptile reviewed commit
`e9eb102e92a7bcfdde6b87ba02949356b8602c46` at 5/5 with no findings.
GitHub CI is still running; this remains a draft for maintainer review.

## Risks

The new guidance could be read too broadly when removing a guard. It
explicitly retains authority and integrity checks. The surrounding skill
still requires a regression for the negative case protected by the old
guard. This change does not alter runtime behavior or grant recovery,
merge, or deployment authority.

## Model Used

OpenAI `gpt-6-astra` through Codex, max reasoning effort, with shell and
GitHub tools. The host reports an effective context window of 258,400
tokens. The preceding retrospective also used OpenAI `gpt-6.1-sol` and
`gpt-6-astra` reviewers at xhigh effort.

## Checklist

- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
- [x] I have not referenced internal/instance-local Paperclip issues or
links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip`
URLs)
- [x] My branch name describes the change (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived details
- [x] I have run tests locally and they pass (skill validation and link
checks; application suites not run)
- [x] I have added or updated tests where applicable (no executable
behavior changed)
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [ ] All Paperclip CI gates are green
- [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [x] I will address all Greptile and reviewer comments before
requesting merge

Co-authored-by: Paperclip <noreply@paperclip.ing>

.agents/skills/fix-failed-paperclip-run/SKILL.md

@@ -32,6 +32,9 @@ available tools and records before asking the user for missing information:
 - Which endpoint is authorized: verified fix and green PR, or also rollout and
   recovery. Preserve the requested work and success criteria throughout.
 
+Use the [bounded run diagnostics reference](../../../skills/paperclip/references/run-diagnostics.md)
+for the repository's existing run, event, log, and recovery reads.
+
 Use authorized diagnostic access. If company scoping blocks a read, use an
 already-authorized diagnostic path or label the missing evidence; do not bypass
 the boundary.
@@ -111,6 +114,10 @@ red-green proof from a test that was first run after the fix.
 
 ## 4. Repair the cause and prove the safety assumptions
 
+Before changing a failing guard, name the invariant it protects. If existing runtime
+checks already establish compatibility, remove redundant prerequisites instead of
+adding qualification machinery; retain authority and integrity checks.
+
 Fix the responsible producer or shared transition at the narrowest correct scope.
 Check sibling callers/adapters that share that contract; generalize only as far as
 the evidence requires. Avoid historical string allowlists, swallowed errors,