- Home
- Skills
- Product Management
- Documentation & ADRs: Write Down the Why
More screenshots
Works with the AI Agents you already use
Documentation & ADRs: Write Down the Why
Capture the why behind technical decisions — architecture decision records for expensive-to-reverse choices, plus living docs (READMEs, API docs, onboarding guides) that keep a codebase legible.
$5
Documentation & ADRs: Write Down the Why
Example session with this skill installed
We are choosing between JWTs and session tokens for our multi-service API, and nobody will remember why in six months. Write the ADR and tell me what living docs need to exist alongside it.
- Read your context and instructions
- Compiled the documentation & adrs
ADR — JWTs vs session tokens (multi-service API)
Context: three services, one web client, one mobile client. Services must validate requests without calling a central auth service every time, and token revocation must work within minutes when an account is compromised.
Alternatives with why each lost: (1) Stateful session tokens — revocation is simple, but every service calls the auth service per request, which is the bottleneck this architecture exists to avoid. (2) JWTs with long expiry — simplest, but revocation is effectively impossible, which fails the compromise requirement outright.
Decision: JWTs, 15-minute access tokens, rotating refresh tokens, denylist checked at refresh time.
Consequences — positive: services validate locally, no auth-service bottleneck. Negative, stated honestly: refresh rotation adds complexity, and the denylist is a new component to operate. Reversal trigger written in the record: if the denylist becomes a bottleneck, revisit stateful sessions.
Living docs alongside it: the README's API section records the token lifetimes and refresh flow; the API docs state the retry semantics for an expired access token; the onboarding guide includes the three gotchas (refresh rotation, denylist checks, clock skew). Status: Accepted, dated, filed as ADR-004 in the repo's existing sequence. In six months, "why not long-lived JWTs?" is answered by the alternatives section — not re-litigated.
Connects securely to your tools. The creator never sees your data.
About this skill
Code shows what was built. Documentation explains why it was built that way and what else was considered — and six months from now, the why is the part that is missing. This skill covers the two highest-value forms: ADRs for decisions that would be expensive to reverse (frameworks, data models, auth strategies, APIs, infrastructure), and living documentation for the codebase (README, API and behavior docs, onboarding guides).
An ADR is short and permanent: context, decision, alternatives with why each lost, honest consequences including the costs, current status, and a reversal trigger. The existing repo convention is matched first — sequence continued, not restarted — and superseded records link forward, never rewritten. A worked example records a JWT-vs-sessions auth decision with the revocation requirement that decided it, so the question never gets re-litigated. Living docs are held to a test: an onboarding guide must get a competent new person to first productive commit. A rubric gates legibility: below 6 out of 8, the why is missing somewhere.
Find more skills like this on the Claude Skills Marketplace, the Codex Skills Marketplace and the Gemini Skills Marketplace, or browse Claude Skills for Product Management.
- It records decisions; it does not make them. The alternatives and consequences must come from the people deciding — the skill structures them, it does not invent them.
- ADRs are reserved for expensive-to-reverse decisions. A decision that took ten minutes and costs nothing to reverse gets a code comment, and the skill will say so.
- Living docs decay: every doc needs an owner and a change-based review trigger, or it rots like any other doc.
- A stale page is deleted rather than left standing — the skill treats a confident lie as worse than an honest gap.
How to use
- 1
Connect your agent to the Agensi MCP
Copy the prompt and paste it into Claude, ChatGPT, Cursor or any agent that supports MCP. It sets up the connection for you. Manual setup
- 2
Sign in to Agensi
Your agent shows a sign-in link. Sign in and click Allow.
- 3
Ask for what you need
Your agent loads this skill and uses it on your task. It always asks before buying a skill.
Reviews
No reviews yet
Be one of the first to try it. Every listed skill goes through the trust checks below.
Security scanned
Checked by our 8-point scan before listing
Fresh listing
Recently published to Agensi
Money-back guarantee
Doesn't do what its page promises? You get your money back.
Trust & safety
Security scan
Security scan passed 3 days ago
Permissions
No special permissions declared or detected