the-archivist

Document engineering decisions as ADRs with rationale and decision logs.

5|3|Updated Oct 23, 2025

Search Tags:#architecture #documentation #decisions #ADR #rationale

Ready to run

npx skills add https://github.com/Cygnusfear/claude-stuff --skill the-archivist

💬 Prompt for ChatGPT / Claude Chat▼

Please help me install this Agent Skill.
Skill: the-archivist
Source: https://github.com/Cygnusfear/claude-stuff/tree/main/skills/the-archivist
Command: npx skills add https://github.com/Cygnusfear/claude-stuff --skill the-archivist

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve?

The Archivist enforces decision documentation for architectural and design choices, ensuring rationale is captured as ADRs and linked to code decisions.

Core Features & Use Cases

ADR Triggers – Document decisions for technology choices, architecture patterns, security decisions, and major design changes.
Decision Taxonomy – Inline comments for micro-decisions; brief ADRs for module-level decisions; full ADRs for system-wide choices.
Documentation Commitment – Integrates with ADR patterns and DECISIONS logs.
Decision Logs – Tracks past decisions and alternatives considered.

Quick Start

When choosing a significant design approach, add an inline decision or a full ADR in .plans/decisions or .plans/ to capture context and rationale.

Frequently Asked Questions about the-archivist

High-intent search queries and answers about installing and using this skill.

FAQPage Schema

Why should I document architectural decisions in my codebase?▼

Documenting architectural decisions captures the rationale behind technology choices, design patterns, and trade-offs, creating an immutable historical record that helps team members understand context and avoid repeating past deliberations.

How do I write an ADR (Architecture Decision Record)?▼

An ADR documents a significant design choice by recording the decision, context, alternatives considered, and rationale. Store ADRs in a structured log or .plans/decisions directory alongside your codebase to maintain traceability with implemented code.

What decisions should I document as ADRs versus inline comments?▼

Use inline comments for micro-decisions within modules, brief ADRs for module-level architectural choices, and full ADRs for system-wide decisions affecting multiple components or technology selection.

Can I integrate decision documentation into my existing development workflow?▼

Yes. ADR documentation integrates with decision logs and templates, allowing you to capture rationale at decision-trigger moments—when selecting frameworks, evaluating security approaches, or planning major refactors—as part of your standard design process.

How do I track alternatives I considered but rejected?▼

Record rejected alternatives and the reasoning behind each choice in your ADRs and decision logs. This documentation prevents revisiting the same trade-offs and preserves institutional knowledge about past evaluations.