Respecting adrs

Skill AInsteinsBR/renata/skills/respecting-adrs

Use whenever you are about to propose a technical solution, write code, or implement a feature. Ensures the proposal respects the project's accepted ADRs before writing a single line of code. Auto-activates when detecting context like "implement X", "how do I Y", "I'm going to use library Z", or similar.From its SKILL.md

Install

npx -y skills add AInsteinsBR/renata --skill respecting-adrs

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

8 stars8 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

SKILL.md

3.5 KB, as published. Nobody here has run it

Respecting ADRs before coding

ADRs (docs/decisions/ADR-*.md) are the project's structural decisions with status accepted. Every technical proposal must respect them — a violation requires opening a new superseding ADR, not bypassing them.

When this skill activates

Auto-activates when the context involves:

"Implement X"
"I'm going to write / code / create"
"Which library to use"
"How do I Y in [language/framework]"
"Refactor to use Z"
Proposing a diff/PR

Procedure (4 steps)

Step 1 — List the relevant accepted ADRs

Run this mentally: "Which ADRs in this project might have something to say about what I'm about to do?"

Always consult docs/decisions/README.md (the index).
If the proposal touches: database → ADR about persistence; auth → ADR about auth; external libraries → ADR about the stack; etc.
If there is no ADR on the topic but the decision is structural → open an ADR first (/adr).

Step 2 — Validate the proposal against each identified ADR

For each relevant ADR:

Read the "Decision" and "Enforcement" sections.
Confirm that the proposal does not contradict the decision.
If the ADR has a hook (.claude/rules.yaml), make sure your code won't be blocked by it.

Step 3 — If there's a conflict, STOP

Don't code. Options:

Refine the proposal to respect the ADR (most common).
Open a new ADR superseding the old one, if the old decision really is wrong (use /adr).
Ask the user for clarification if the conflict isn't clear.

NEVER work around the hook or use a silent workaround.

Step 4 — Cite the ADR in the commit/PR

When implementing, mention the relevant ADR:

feat(providers): ClienteRepo em providers/impl (ADR-007 adapter pattern)

Examples

✅ Good

User: "I'm going to add a cache lib to the worker to store responses."

Skill activates: "Before coding, I'll consult the ADRs. ADR-004 defines technology X for path A, OK. But this cache is a different kind (key-value) and ADR-004 doesn't cover that use. I'll reuse the same infrastructure already available with a dedicated prefix. It doesn't violate ADR-004 or create a new structural decision (caching is an implementation detail)."

❌ Bad

User: "I'm going to add a second database to persist sessions."

Skill does NOT activate, or activates but is ignored: "I added the driver and created the sessions table..."

Result: violates ADR-006 (that database is OUT of scope for the current phase). The hook won't block it (there's no rule), but a structural decision was made without an ADR. Technical debt created.

❌ Worse

User: "I need to use library Z for a specific case."

Skill activates: "ADR-002 explicitly forbids library Z. The hook will block it. I'll use it anyway and add a # noqa on the import."

NO. If you really need it, open ADR-009 superseding ADR-002 with concrete justification. Otherwise, rework the proposal.

Anti-patterns of this skill

❌ "I already know this ADR doesn't apply" without reading — always read.
❌ Citing an ADR in the commit but not having actually validated it.
❌ Skipping Step 1 ("obviously it complies") — it's not obvious until confirmed.