Refactor: split the monolithic `remediation-doctrine.md` into progressive-disclosure modules

[Jiri-Stary]

Summary

scan-secrets/references/remediation-doctrine.md has grown into a single ~720-line reference, and a near-identical ~705-line copy now lives in triage-incidents/references/remediation-doctrine.md. This works against the repo's own "progressive disclosure" design principle and creates a duplicate-and-drift maintenance problem. This issue proposes splitting the doctrine into a slim core plus a handful of focused sibling files (lifecycle tracks + per-secret-type families), keeping the existing section numbering so cross-references stay valid.

Problem

1. The doctrine is a monolith. scan-secrets/references/remediation-doctrine.md is ~720 lines covering principles, the four triage axes, the four deliverable modes, four lifecycle tracks (§5–8), and a per-secret-type appendix (§9.1–9.10). When an agent hits a single finding — say one AWS key leaked to a public repo — it pulls the entire file into context, including every other secret type and every other lifecycle track it doesn't need.

2. It contradicts the repo's stated design principle. The README lists Progressive disclosure as a core design choice: "SKILL.md stays short enough to load quickly; long remediation, setup, and workflow details live in references/." The remediation reference is the one place that principle isn't applied to the reference layer itself.

3. It's duplicated and already drifting. triage-incidents/references/remediation-doctrine.md is a ~705-line "tailored sibling" of the scan-secrets doctrine (the file itself notes it is "kept structurally diffable," with the pre-leak track omitted). Two ~700-line copies of the same doctrine means every future edit has to be mirrored by hand, and the two are already ~15 lines apart.

4. The doctrine is explicitly a shared contract. The doctrine states it drives "the open-source skills shipped from this repo, the in-app agent inside the GitGuardian product, and future profiles." A shared contract is exactly the kind of artifact that benefits from a modular layout that multiple skills/profiles can compose, rather than each copying the whole thing.

Proposed solution

Decompose the doctrine into a slim core (the universal contract) plus focused sibling references, each one hop from SKILL.md. Preserve the existing §-numbering across files so every existing cross-reference (§ 9.1, § 7, etc.) stays accurate.

Suggested layout:

Content (upstream section numbers)	File
§1–4 (principles, triage axes, deliverable modes, implementation profiles) + §10–12 (coordination framework, public-leak takedown, validation)	remediation-doctrine.md (slim core)
§5–8 lifecycle tracks (pre-leak, post-leak/public, post-leak/internal-private, off-repo)	remediation-lifecycle-tracks.md
§9.1 AWS, §9.8 GCP, §9.9 Azure	remediation-cloud-keys.md
§9.2 GitHub PAT, §9.3 generic API key, §9.6 Stripe, §9.7 Slack, §9.10 OAuth refresh tokens	remediation-saas-tokens.md
§9.4 DB connection URLs, §9.5 private keys	remediation-keys-and-dbs.md
Quick pointer / router	remediation.md (optional)

triage-incidents would then reference the same shared modules (it can simply skip the pre-leak track) instead of carrying a second full copy.

Concrete example (an implementation we've validated)

We applied this split and it holds up well in practice. Line counts of the resulting files:

remediation-doctrine.md            141   # slim core: principles, triage axes, deliverable modes, profiles, coordination, takedown, validation
remediation-lifecycle-tracks.md    100   # §5–8 lifecycle tracks
remediation-cloud-keys.md          195   # §9.1 AWS, §9.8 GCP, §9.9 Azure
remediation-saas-tokens.md         196   # §9.2 GitHub, §9.3 generic, §9.6 Stripe, §9.7 Slack, §9.10 OAuth
remediation-keys-and-dbs.md        143   # §9.4 DB URLs, §9.5 private keys
remediation.md                      24   # router / quick pointer

The slim core keeps the universal contract and points outward, e.g.:

## Contents
This core file carries the universal contract:
1. Principles
2. The four triage axes
3. The four deliverable modes
4. Implementation profiles
10. Generic coordination framework
11. Public-leak takedown / reporting
12. Validation

Sections 5–9 have moved to flat sibling reference files (each linked one hop from the
scan-secrets SKILL.md). Section numbering is preserved across the split so cross-references
stay accurate:
- § 5–§ 8 — Lifecycle tracks: remediation-lifecycle-tracks.md
- § 9 — Per-secret-type appendix, split by credential family:
  - Cloud provider keys (§ 9.1 AWS, § 9.8 GCP, § 9.9 Azure): remediation-cloud-keys.md
  - SaaS / API tokens (§ 9.2 GitHub, § 9.3 generic, § 9.6 Stripe, § 9.7 Slack, § 9.10 OAuth): remediation-saas-tokens.md
  - Database URLs & private keys (§ 9.4 DB URLs, § 9.5 private keys): remediation-keys-and-dbs.md

Before / after, structurally:

# before
scan-secrets/references/remediation-doctrine.md      (~720 lines, everything)
triage-incidents/references/remediation-doctrine.md  (~705 lines, near-duplicate)

# after
scan-secrets/references/
  remediation-doctrine.md            (slim core)
  remediation-lifecycle-tracks.md
  remediation-cloud-keys.md
  remediation-saas-tokens.md
  remediation-keys-and-dbs.md
triage-incidents/  → references the same shared modules (skips the pre-leak track)

Benefits

• Honors progressive disclosure — an agent loads the slim core plus only the relevant track + secret-type file, instead of ~720 lines for every finding.
• Removes the duplicate — scan-secrets and triage-incidents share the same modules; no more mirroring edits across two ~700-line copies, and no drift.
• Easier to review and extend — adding/refining a single secret type (e.g. a new cloud provider) is a small, focused diff in one file rather than an edit buried in a 720-line document.
• Backward-compatible references — preserving §-numbering keeps all existing in-text cross-references valid.

[mathieubellon]

Hello @Jiri-Stary

I completely understand the point. To clarify its origin, it was designed this way because users can, potentially, download or activate only one skill at a time (notably via skills.sh, one of our distribution channel). Therefore, each skill must be atomic and include a complete bundle of everything it requires.

Even with a full plugin distribution with all skills our target models (Sonnet, Haiku) had, sometimes, problems to reach for a common reference file in our first implementation (where we were following a stricter DRY approach)

Some user are asking for a spec improvement around this question

That said, I am not entirely satisfied with the drawbacks of this design in the long run and I would be happy to revisit this

And, also, progressive disclosure must be adressed anyway, I agree. I leave the issue open to drive some more tests and find a better approach