---
name: nanlabs-adr
description: >-
  WHAT, Create and maintain Architecture Decision Records (ADRs) per the NaNLABS process in ClickUp. Covers when to write an ADR, required sections, review, and linking to epics/PRs. English for cross-team artifacts unless the user asks otherwise.
---

# ADR, Architecture Decisions (WHAT)

**Canonical source:** the ADR workflow page in ClickUp. Ask internally for the current link; use the local template below as the distributable source.

## Default guardrails (before any final content)

1. Apply **`nanlabs-output-handshake`**: confirm **where** the final ADR will be recorded and that a **human** will review.
2. Then follow the steps below.

## When to use

Use **`nanlabs-decision-log`** for lightweight product/project/operational decisions and **`nanlabs-agreement`** for explicit commitments or terms among parties. Use this ADR skill only for durable architecture or technical decisions.


- A change has **long-term** architectural, security, data-model, or cost impact.
- You need **options with pros/cons** and a **record** for future readers (and for supersession later).
- The project needs decisions linked to PRDs, TRDs, tasks, PRs, diagrams, or other supporting artifacts.

## Instructions

1. **Confirm the decision qualifies** (new service, tech selection, schema change, deployment change, etc.) per the ClickUp “When to Create an ADR” list.
2. **Draft** using the six-part structure: Title & status, Context, Options, Decision, Consequences, References (link **PRD/TRD**, tasks, PRs, diagrams as applicable).
3. **Review** with the tech lead / peers as in the workflow; keep ADRs **short and actionable** (clarity over completeness).
4. **Link** the ADR to the relevant **epic or story** and to **PRs** in the forge (use **`github-cli-workflow` / `gitlab-cli-workflow`** for PR text when applicable).
5. If an ADR is **superseded**, **preserve history**: update status and point to the replacement document.

## What not to do

- Do not use an ADR for one-line fixes with no long-term effect (use a normal task or PR description).
- Do not paste the full org policy from ClickUp into the skill; keep a single **canonical** copy in the wiki.

## References

- `nanlabs-architect` agent — trade-off analysis and `references/PATTERNS.md` (SOLID, Clean Architecture) before drafting options
- `nanlabs-output-handshake`, destination and review
- `references/default-template.md`, local ADR template structure
- `references/example-001-graphql-adoption.md` — example ADR for a GraphQL migration decision
- `nanlabs-trd`, where technical design references decisions
- `nanlabs-decision-log`, lightweight decisions
- `nanlabs-agreement`, explicit commitments or terms
- `nanlabs-workflow-generic-project`, traceability and plan approval
- `clickup-cli`, task and comment operations