Review agent: suppress content-security URL findings in documentation files

[fullsend-ai-retro]

What happened

On PR #1483, the review agent flagged a Cloud Run URL in docs/guides/admin/install.md as [high] content-security, recommending it be replaced with an environment variable. The URL was intentionally hardcoded — the install guide needed to show users the actual endpoint to configure. The human author replied explaining this, but the agent re-flagged the same URL on the next review pass. This false positive consumed author attention across two review cycles.

What could go better

The content-security heuristic that detects hardcoded URLs/secrets does not distinguish between executable code (where hardcoded credentials are a real risk) and documentation (where showing actual URLs is often the point). A URL in a markdown file under docs/ cannot be exploited the same way as one in source code — it is descriptive, not operative. The review agent should calibrate its content-security scanning based on file type: markdown/docs files should have a much higher bar for URL-based security findings. Confidence: high — this is a clear category error in the heuristic. The agent correctly identifies that hardcoded URLs can be a security concern, but misapplies that rule to documentation where hardcoded URLs are expected and appropriate.

Proposed change

In the code-review skill (internal/scaffold/fullsend-repo/skills/code-review/SKILL.md), add guidance to the content-security evaluation dimension: when the file under review is documentation (markdown, RST, or similar non-executable format under docs/), URLs and service endpoints should not be flagged as content-security findings unless they contain obvious secrets (tokens, API keys, passwords). Hardcoded URLs in documentation are expected and should be treated differently from hardcoded URLs in source code. This could be implemented as a file-type-aware severity modifier: content-security findings about URLs in docs/**/*.md files should be capped at [info] severity unless the URL contains path segments that look like secrets.

Validation criteria

On the next 5 documentation-only PRs reviewed by the review agent, none should receive a [high] or [medium] content-security finding solely for containing a URL in a markdown file. If a docs PR does contain an actual secret (API key, token), it should still be flagged. Timeframe: next 30 days or 5 docs PRs, whichever comes first.

---

Generated by retro agent from #1483

[fullsend-ai-triage]

Triage Summary

This is a well-defined enhancement to the code-review skill's content-security dimension. The review agent currently applies the same URL/secret detection heuristic to documentation and source code, causing false positives when docs files contain hardcoded URLs — which is expected and appropriate in install guides and configuration docs.

Severity: Medium — false positives erode trust in the review agent and waste author time across review cycles.

Proposed change location: internal/scaffold/fullsend-repo/skills/code-review/SKILL.md, in the "Content security" section (~line 109). Add file-type-aware guidance: when reviewing non-executable documentation formats (markdown, RST) under docs/, URLs and service endpoints should not be flagged as content-security findings unless they contain obvious secret material (tokens, API keys, passwords). URL-only findings in docs files should be capped at [info] severity.

Proposed test case:

Scenario 1 — URL in docs (should NOT trigger high/medium):
  Given a PR modifying docs/guides/admin/install.md
  And the file contains a service URL (e.g., a Cloud Run endpoint)
  When the review agent evaluates content-security
  Then no finding above [info] severity is produced for the URL

Scenario 2 — Actual secret in docs (should STILL trigger high):
  Given a PR adding an API key (e.g., APIKEY=sk-abc123...) to a docs/ markdown file
  When the review agent evaluates content-security
  Then a [high] content-security finding is produced

Edge case: markdown files outside docs/ (e.g., root README) with URLs
  should also benefit from relaxed heuristic.

Validation criteria from the issue: Over the next 5 documentation-only PRs, none should receive a [high] or [medium] content-security finding solely for containing a URL in a markdown file.

---

Labels: This is a retro-filed feature enhancement to the code-review skill, affecting the review agent's content-security dimension, at medium priority.