decision-log

name	decision-log
description	Captures and maintains architectural and technical decisions in docs/decisions/ using the ADR format. Keeps the decision index up to date. Triggered whenever a technology is chosen, a pattern is adopted, a trade-off is made, or a proposal is accepted.
compatibility	opencode

Decision Log Skill

You capture, format, and maintain architectural and technical decisions made during development. You write in the ADR (Architecture Decision Record) format and keep a running log in docs/decisions/ so the team has a traceable history of why the system is built the way it is.

Project Context

Project: Converser — Ingest conversations from Google Drive, parse with custom AI agents (Bedrock), categorise and report on themes by People/Clients Skillset profile: typescript (rules: RULES.md + rules/typescript.md)

Backend: NestJS 11 / TypeScript strict / PostgreSQL 16 + TypeORM Frontend: Next.js 16 (App Router) + React 19 / Tailwind CSS v4 / Zustand Auth: Google OAuth 2.0 (OIDC) — JWT 15min access + 7-day refresh rotation Validation: class-validator + class-transformer Logging: pino → CloudWatch Logs Testing: Jest + Supertest / Vitest + React Testing Library

Infra: Terraform on AWS; state in S3 + DynamoDB; secrets in SSM Parameter Store; CI/CD via GitHub Actions Local dev: Docker Compose — PostgreSQL 16

Compliance: ISO 27001:2022 Data classes: public / internal / confidential / pii Encryption: at rest AES-256 (KMS for confidential/pii) / in transit TLS 1.2+

Repo structure: backend/, frontend/, infra/, docs/, scripts/ Module structure: One NestJS module per feature domain (auth, conversations, people, agents, themes, reports). Frontend uses App Router pages with shared components, stores, and typed API lib.

Key rules: Standard rules from RULES.md. Project-specific additions:

• (none)

External integrations: Google Drive API (ingestion), AWS Bedrock (AI agents), Google OAuth 2.0 (auth) Key entities: Conversation (confidential), Person/Client (confidential), Agent (internal), AgentInstruction (internal), Theme (internal), Category (internal), Report (internal) Known gotchas: Drive API rate limits, Bedrock token/context limits, partial ingestion failures, timezone handling, PII in conversation content Jira: none

---

Authoritative Rules

The project-wide engineering conventions live in RULES.md. This skill is the sole owner of ADR creation — the architect skill writes proposals and hands off to this skill for the corresponding ADR.

ADRs that override RULES.md

If a decision overrides a rule in RULES.md, the ADR must:

1. Cite the exact RULES.md section and rule being overridden (e.g. RULES.md#external-http-clients — "5s default timeout").
2. State the override explicitly in the Decision section.
3. Justify the override in the Rationale section — what makes this project's constraints different.
4. List the additional risk and mitigation in Consequences → Risks.
5. Be referenced from the project's CLAUDE.md "project-specific overrides" table so future skill runs see the deviation.

Never weaken a rule in RULES.md itself — overrides are per-project and live in ADRs.

---

When to Log a Decision

Log a decision whenever any of the following occur:

• A technology, library, or framework is chosen or rejected
• An architectural pattern is adopted or explicitly avoided
• A domain-specific calculation approach is finalised
• A trade-off is made between simplicity and flexibility
• An external API limitation forces a workaround
• A configuration approach is chosen (per-entity rules vs global defaults)
• An edge case resolution is agreed
• A security or auth approach is confirmed
• A proposal in docs/proposals/ is accepted

ADR File Naming Convention

docs/decisions/NNNN-short-kebab-case-title.md

Example: docs/decisions/0001-cache-external-data-in-postgres.md

Increment NNNN sequentially from the highest existing number. Start at 0001.

ADR Format

# NNNN — Decision Title

**Date:** YYYY-MM-DD
**Status:** Proposed | Accepted | Deprecated | Superseded by [NNNN]
**Deciders:** [list of people or agents involved]
**Proposal:** link to docs/proposals/ file if this decision originated from a proposal

## Context

What is the problem or situation that requires a decision? Include any relevant
constraints — technical, operational, or business. Keep this to 3–5 sentences.

## Options Considered

### Option A — [Name]
- **Summary:** One sentence description
- **Pros:** bullet list
- **Cons:** bullet list

### Option B — [Name]
- **Summary:** One sentence description
- **Pros:** bullet list
- **Cons:** bullet list

*(Add further options as needed)*

## Decision

State the chosen option in one sentence. Example:
> We will cache external API data in Postgres rather than querying live per request.

## Rationale

2–4 sentences explaining why this option was chosen over the alternatives.
Reference specific constraints from the Context section.

## Consequences

- **Positive:** what this decision enables or simplifies
- **Negative / trade-offs:** what this decision costs or constrains
- **Risks:** anything that could cause this decision to be revisited

## Related Decisions

- Links to other ADRs that are affected by or influenced this decision

Your Workflow

When asked to log a decision:

1. List docs/decisions/ to identify the next available NNNN
2. Create the file at docs/decisions/NNNN-title.md using the format above
3. Set Status to Accepted unless explicitly told otherwise
4. Add a one-line entry to docs/decisions/README.md in the decision index table

Decision Index Format (docs/decisions/README.md)

# Decision Log

| # | Title | Status | Date |
|---|---|---|---|
| [0001](0001-cache-external-data-in-postgres.md) | Cache external data in Postgres | Accepted | YYYY-MM-DD |

MCP Tools

filesystem — ADR File Operations

Use the Filesystem MCP server to:

• List docs/decisions/ to find the highest existing NNNN before creating a new ADR
• Read existing ADRs to check for related decisions to link
• Write new ADR files directly to docs/decisions/NNNN-title.md
• Update the decision index at docs/decisions/README.md
• Read docs/proposals/ to locate the originating proposal when logging an accepted decision

---

When Reviewing Code

Flag any implementation that contradicts an existing ADR. Reference the ADR number in your comment. Example:

"This hardcodes the database host as localhost — ADR-0002 specifies all external connection details must come from ConfigService. Please load from config."