gitscape.ai: Skill for Claude Code

Documentation and Architecture Decision Records

Overview

Document the why, not the what. Code explains what it does. Documentation explains why it does it that way, what alternatives were rejected, and what constraints apply. Architecture Decision Records (ADRs) are the canonical tool for capturing decisions that would be painful to reverse.

When to Use

• Making an architectural decision (choosing a library, pattern, or approach)
• Changing a public-facing API
• Adding a new feature that introduces a non-obvious constraint
• Resolving a significant technical debate
• Any decision that future agents or engineers would otherwise re-litigate

Architecture Decision Records (ADRs)

An ADR is a short document that records a single decision. It is immutable — once made, an ADR is never edited. Superseding decisions get a new ADR.

ADR Location

.agents/decisions/
  ADR-001-skill-assembly-approach.md
  ADR-002-secret-management-gcp.md
  ADR-003-file-preview-truncation.md

ADR Template

# ADR-[NNN]: [Short descriptive title]

**Date:** YYYY-MM-DD  
**Status:** Proposed | Accepted | Superseded by ADR-[NNN]  
**Deciders:** [Who was involved]

## Context

What situation or problem prompted this decision? Include constraints,
requirements, and any relevant background. Keep this to 1-3 paragraphs.

## Decision

The decision that was made. State it clearly and directly:
"We will use X because Y."

## Alternatives Considered

| Alternative | Why Rejected |
|---|---|
| Option A | Reason it was ruled out |
| Option B | Reason it was ruled out |

## Consequences

**Positive:**
- What becomes easier or possible

**Negative / Trade-offs:**
- What becomes harder or is given up

## See Also
- Link to related ADRs, docs, or issues

ADR Examples for GitScape

# ADR-001: Use Cloud Run for API Hosting

**Date:** 2026-06-01
**Status:** Accepted

## Context
GitScape's API is stateless — no database, no persistent file storage.
Requests process a GitHub repository and return a generated skill zip.

## Decision
Host the API on Cloud Run (fully managed) rather than GKE or GCE.

## Alternatives Considered
| Alternative | Why Rejected |
|---|---|
| GKE | Requires cluster management; no benefit for a stateless service |
| GCE | Requires OS management; too much operational overhead |
| App Engine | Less flexible for Python async workloads; Cloud Run preferred |

## Consequences
**Positive:** Zero cluster management, scales to zero, pay-per-use.
**Negative:** Cold start latency (~1-2s) on first request after idle.