JosiahSiegel/adr-discovery
plugins/doc-master/skills/adr-discovery/SKILL.md
This skill should be used before drafting an ADR when context, components, relationships, deciders, or prior decisions are unclear. PROACTIVELY activate on "I want to write an ADR for X", "gather context for a decision", "discovery for an ADR", "ADR intake", "ADR pre-flight", "prep work before an ADR", "what's the current architecture?", or "set up a decision log." Provides: zero-hallucination Q&A, human-confirmed discovery brief, open-questions register, and five required confirmations before drafting.
$ install --global
skillsauthnpx skillsauth add JosiahSiegel/claude-plugin-marketplace adr-discoveryInstall this skill globally with one command. Works with Claude Code, Cursor, and Windsurf.
Security Scan Results
3 of 9 scanners reported clean
Some scanners were skipped, did not run, or reported a non-clean status. Review each row below.
3
Scanners Passed
9
Scanners in report
Clean
TrivyContainer and dependency vulnerability scanner
95%
Clean
SemgrepStatic code analysis for vulnerabilities
95%
Clean
mcp-scan (Snyk)Model Context Protocol security validation
95%
Skipped
Snyk (dep)Open source security scanning
50%
Skipped
Socket.devSupply chain security analysis
50%
Skipped
VirusTotalMulti-engine malware detection
50%
Skipped
CrowdStrikeAdvanced threat intelligence
50%
Skipped
OSV-ScannerOpen Source Vulnerability database check
50%
Skipped
OWASP Dep-Check
50%
Last scanned: May 21, 2026, 7:59 AM129.7s3 files scanned
SKILL.md
- name:
- adr-discovery
- description:
- |
- Provides:
- zero-hallucination Q&A, human-confirmed discovery brief, open-questions register, and five required confirmations before drafting.
adr-discovery
Pre-flight context gathering for an ADR. The output is a docs/architecture/discovery-brief.md containing only human-confirmed facts, plus a docs/architecture/open-questions.md register of unknowns. The architect then hands off to adr-drafting to actually draft the decision.
Core rule: zero hallucination
No fact enters the discovery brief until the architect says yes. Code findings, doc findings, and inferences are all presented as questions, never as assertions.
| Wrong | Right |
|---|---|
| "Your system uses Postgres and Redis." | "I see pg and ioredis in package.json. Is Postgres your primary store? (yes / no / unsure)" |
| "Component A talks to component B." | "I see a fetch from A to B in src/a/client.ts. Does A depend on B? (yes / no)" |
Every confirmed fact is dated and tagged in the brief: [CONFIRMED YYYY-MM-DD]. Unconfirmed code findings get [FROM CODE, UNCONFIRMED YYYY-MM-DD] and live in open-questions.md, not the brief.
Fact states
| State | Where it lives | Allowed to drive a decision? |
|---|---|---|
| CONFIRMED | discovery-brief.md | Yes |
| FROM CODE, UNCONFIRMED | open-questions.md | No |
| UNKNOWN | open-questions.md | No |
| PARKED | open-questions.md (with reason) | No — must be noted in ADR Consequences |
Vocabulary (define on first use)
- Component — a runnable / deployable unit (C4 Container). Not a code class.
- System — the one bounded product in focus for this ADR. Exactly one.
- External system — a system the team does not own but interacts with.
- Actor — a human role (Person in C4 terms).
- Architectural characteristic — the non-functional quality under pressure (latency, cost, maintainability, availability, security posture, etc.).
- Tension — two ADRs that conflict without one superseding the other. A tension is a fact, not a failure; it must be acknowledged.
- RFC — a proposal-stage doc. ADRs are for decisions already made.
Style
- One topic at a time. Never ask two questions in one turn.
- Restate the architect's answer in your own words before recording it.
- Direct. Skip "Great question!", "Excellent!", and other affirmations.
- Name specific files, tech, and components — never vague nouns ("the service," "the database").
- If a turn would contain more than one
?or run more than a short paragraph, shorten it.
The nine phases
1. Scan, don't summarize
Glob the repo for signals — never assert what you find.
- ADR directories:
docs/adr/,docs/decisions/,docs/architecture/decisions/,**/adr/*.md; also check legacyarchitecture/decisions/and warn it may need custom ADR Explorer root configuration - Manifests:
package.json,pyproject.toml,Cargo.toml,go.mod,pom.xml,*.csproj - READMEs at the repo root and one level down
- LikeC4 files:
**/*.c4,likec4.config.* - Existing
discovery-brief.md/open-questions.md
Report raw findings only: "I found these files: X, Y, Z. I have not interpreted them yet." Then ask: "Should I walk through them with you one at a time, or do you want to start from a clean slate?"
Optionally offer live diagram mode — see references/live-diagram-mode.md — but only after the architect opts in.
2. Confirm domain
Ask exactly one question: "What does this system do, and for whom?"
Wait for an answer. Restate. Confirm. Then write a single Domain: line to the brief.
3. Confirm components one at a time
Define Component (a C4 Container — a deployable unit). Then walk candidates one by one. For each:
- State the candidate name as you found it (in the manifest, the README, the LikeC4 file, or the architect's words).
- Ask: "Is this a component in scope for this decision? (yes / no / out of scope)"
- If yes: ask for a one-line description in the architect's words.
- If no: drop it.
- Hard limit: 5 components. If the architect names a 6th, ask whether the decision is bundled.
4. Confirm relationships with human-written descriptions
For each confirmed component pair, ask: "Does A depend on B? If yes, in one line, what does A use B for?"
A relationship without a human-written description does not enter the brief. "A talks to B" is not a description.
5. Confirm existing ADRs
Glob the ADR directory. For each ADR, ask one of:
- Supersedes? — does this new decision replace this prior one?
- Amends? — does it adjust without replacing?
- Relates-to? — does it share context but stand alone?
- Tension? — does it conflict, with neither superseding?
- Unrelated? — drop it.
Only the architect's answer enters the brief. Inference does not.
6. Multi-repo + ecosystem probe
Many decisions cross repo boundaries. Ask per related repo:
- Role (consumer / producer / shared library / platform)
- Owner (named team or person)
- Access (read / write / no access)
- Existing ADRs in that repo
- Existing C4 / architecture diagrams
Beyond repos, ask whether the org has:
- A wiki / Backstage / TechRadar / platform-level ADR set
- Compliance constraints (data residency, SOC2, HIPAA, GDPR, FedRAMP) that bind the decision
- A platform team whose decisions the architect inherits
7. Checklist gate
Before hand-off, all five MUSTs must be CONFIRMED:
| MUST | Confirmed when… | |---|---| | Domain | Architect has stated what the system does and for whom | | Architectural characteristic under pressure | Architect named the quality being optimized (latency / cost / availability / etc.) and the specific number or condition forcing the decision | | ≤5 components in scope | Architect confirmed each by name, with a one-line description | | Related ADRs classified | Each existing ADR classified or explicitly dropped | | Named decision-maker | Specific human(s) — not "the team," not "leadership" |
If any MUST is UNKNOWN or PARKED, the skill refuses to advance and routes to open-questions.md.
8. C4 handoff (optional)
If the architect wants a diagram before drafting, hand off to c4-model (canonical C4: Context + Container views only). Skip if they don't.
9. Handoff to drafting
When all five MUSTs are confirmed, write a one-line summary at the bottom of discovery-brief.md:
Discovery complete: 2026-05-20. Hand off to adr-drafting.
The drafting skill reads the brief and does not re-ask anything in it.
Living files (kept deliberately outside ADR-parsed directories)
docs/architecture/discovery-brief.md and docs/architecture/open-questions.md are intentionally not under docs/adr/, so ADR-parser tools and indexes don't mistake them for ADRs.
discovery-brief.md shape
# Discovery Brief
## Domain
[CONFIRMED 2026-05-20] One sentence -- what does the system do, for whom.
## System in focus
[CONFIRMED 2026-05-20] Single named system.
## Architectural characteristic under pressure
[CONFIRMED 2026-05-20] e.g., "p95 read latency < 200ms on cross-entity reports."
## Components in scope (≤5)
[CONFIRMED 2026-05-20] - Name -- one-line description (architect's words)
...
## Relationships
[CONFIRMED 2026-05-20] - A → B: A uses B to <verb phrase>
...
## External actors
[CONFIRMED 2026-05-20] - Role -- one-line description
...
## Existing ADRs in play
[CONFIRMED 2026-05-20] - 0007 -- supersedes / amends / relates-to / tension
## Repos in play
[CONFIRMED 2026-05-20] - repo: role / owner / access / ADRs / C4
## Ecosystem constraints
[CONFIRMED 2026-05-20] - Compliance, platform, wiki/Backstage hits
## Decision-makers
[CONFIRMED 2026-05-20] - Named human(s)
---
Discovery complete: 2026-05-20. Hand off to adr-drafting.
open-questions.md shape — see references/open-questions-register.md for the full schema.
The "ADR IS NOT" rules apply here too
Even during discovery, do not tutorialize, hedge, or invent. See ../_shared/adr-is-not.md for the shared checklist.
References
references/live-diagram-mode.md— opt-in LikeC4 live-diagram workflow during discoveryreferences/open-questions-register.md— schema and discipline foropen-questions.md../_shared/adr-is-not.md— shared "ADR is not" checklist
Related Skills
JosiahSiegel/ml-training
development
VerifiedTrustedCommunity
This skill should be used when the user asks to train, debug, scale, or improve ML models. PROACTIVELY activate for: (1) PyTorch, TensorFlow/Keras, JAX, Flax, Hugging Face Trainer/Accelerate training loops, (2) distributed training, DDP/FSDP/DeepSpeed, TPU/GPU setup, (3) mixed precision AMP/bf16, gradient accumulation, checkpointing, seeding, (4) overfitting, imbalance, loss functions, regularization, LR schedules, warmup, (5) memory optimization, gradient checkpointing, offloading, quantization-aware training. Provides: reproducible training best practices across deep learning and classical ML.
38SKILL.mdUpdated May 28, 2026
JosiahSiegel/ml-mlops
development
VerifiedTrustedCommunity
This skill should be used when the user asks to productionize, track, version, govern, monitor, or automate ML systems. PROACTIVELY activate for: (1) MLflow, Weights & Biases, Neptune, Comet, ClearML experiment tracking, (2) model registry, model versioning, artifact lineage, reproducibility, (3) Kubeflow, SageMaker Pipelines, Vertex AI Pipelines, Azure ML pipelines, Databricks workflows, (4) CI/CD, continuous training/evaluation, A/B tests, canary/shadow deployments, (5) drift detection, model monitoring, data validation, responsible AI governance. Provides: end-to-end MLOps architecture and operational safeguards.
38SKILL.mdUpdated May 28, 2026
JosiahSiegel/ml-inference-optimization
development
VerifiedTrustedCommunity
This skill should be used when the user asks to optimize, export, serve, compress, or accelerate ML inference. PROACTIVELY activate for: (1) latency, throughput, p95/p99, batching, concurrency, KV cache, memory, or cost issues, (2) quantization INT8/INT4, GPTQ, AWQ, bitsandbytes, pruning, sparsity, distillation, (3) ONNX export, ONNX Runtime, TensorRT, TorchScript, torch.compile, XLA, OpenVINO, Core ML, TFLite, (4) Triton, TorchServe, TF Serving, BentoML, Seldon, KServe configuration, (5) edge deployment, CPU/GPU/TPU/Inferentia serving. Provides: hardware-aware inference optimization and safe benchmarking.
38SKILL.mdUpdated May 28, 2026
JosiahSiegel/ml-hyperparameter-tuning
testing
VerifiedTrustedCommunity
This skill should be used when the user asks to tune hyperparameters, run sweeps, optimize search spaces, or use AutoML. PROACTIVELY activate for: (1) Optuna, Ray Tune, FLAML, AutoGluon, Hyperopt, Nevergrad, KerasTuner, W&B sweeps, (2) grid search, random search, Bayesian optimization, TPE, Gaussian processes, evolutionary search, (3) ASHA, Hyperband, successive halving, multi-fidelity optimization, population-based training, (4) learning-rate finder, batch-size search, early stopping, pruning, (5) reproducible sweep design and experiment analysis. Provides: budget-aware hyperparameter search strategy.
38SKILL.mdUpdated May 28, 2026