documentation-and-adrs

Name: documentation-and-adrs
Author: jmxt3

32stars3forks

How to install documentation-and-adrs?

jmxt3/gitscape.ai/documentation-and-adrs

$npx -y skills add jmxt3/gitscape.ai --skill documentation-and-adrs

Installs into the current project.

Summary

Records decisions and documentation. Use when making architectural decisions, changing public APIs, shipping features, or when you need to record context that future engineers and agents will need to understand the codebase.

Files · 1

View on GitHub

SKILL.md

1	# Documentation and Architecture Decision Records
2
3	## Overview
4
5	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.
6
7	## When to Use
8
9	- Making an architectural decision (choosing a library, pattern, or approach)
10	- Changing a public-facing API
11	- Adding a new feature that introduces a non-obvious constraint
12	- Resolving a significant technical debate
13	- Any decision that future agents or engineers would otherwise re-litigate
14
15	## Architecture Decision Records (ADRs)
16
17	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.
18
19	### ADR Location
20
21	```
22	.agents/decisions/
23	ADR-001-skill-assembly-approach.md
24	ADR-002-secret-management-gcp.md
25	ADR-003-file-preview-truncation.md
26	```
27
28	### ADR Template
29
30	```markdown
31	# ADR-[NNN]: [Short descriptive title]
32
33	Date: YYYY-MM-DD
34	Status: Proposed \| Accepted \| Superseded by ADR-[NNN]
35	Deciders: [Who was involved]
36
37	## Context
38
39	What situation or problem prompted this decision? Include constraints,
40	requirements, and any relevant background. Keep this to 1-3 paragraphs.
41
42	## Decision
43
44	The decision that was made. State it clearly and directly:
45	"We will use X because Y."
46
47	## Alternatives Considered
48
49	\| Alternative \| Why Rejected \|
50	\|---\|---\|
51	\| Option A \| Reason it was ruled out \|
52	\| Option B \| Reason it was ruled out \|
53
54	## Consequences
55
56	Positive:
57	- What becomes easier or possible
58
59	Negative / Trade-offs:
60	- What becomes harder or is given up
61
62	## See Also
63	- Link to related ADRs, docs, or issues
64	```
65
66	### ADR Examples for GitScape
67
68	```markdown
69	# ADR-001: Use Cloud Run for API Hosting
70
71	Date: 2026-06-01
72	Status: Accepted
73
74	## Context
75	GitScape's API is stateless — no database, no persistent file storage.
76	Requests process a GitHub repository and return a generated skill zip.
77
78	## Decision
79	Host the API on Cloud Run (fully managed) rather than GKE or GCE.
80
81	## Alternatives Considered
82	\| Alternative \| Why Rejected \|
83	\|---\|---\|
84	\| GKE \| Requires cluster management; no benefit for a stateless service \|
85	\| GCE \| Requires OS management; too much operational overhead \|
86	\| App Engine \| Less flexible for Python async workloads; Cloud Run preferred \|
87
88	## Consequences
89	Positive: Zero cluster management, scales to zero, pay-per-use.
90	Negative: Cold start latency (~1-2s) on first request after idle.
91	```
92
93	## Inline Code Documentation
94
95	### When to Write Comments
96
97	```python
98	# GOOD: Explains WHY, not WHAT
99	# GitHub's API rate-limits to 5000 requests/hour for authenticated users.
100	# We batch file fetches to minimize API calls during skill generation.
101	async def fetch_repo_files_batched(repo: str) -> list[File]:
102	...
103
104	# BAD: Explains WHAT (the code already does this)
105	# Loop through files and add to list
106	for f in files:
107	result.append(f)
108	```
109
110	### Docstrings
111
112	Write docstrings for all public functions in the API:
113
114	```python
115	async def generate_skill(repo: str, tier: str = "standard") -> SkillBundle:
116	"""Generate a skill bundle from a GitHub repository.
117
118	Args:
119	repo: GitHub repository in "owner/repo" format.
120	tier: Skill tier. "standard" uses the base model;
121	"hd" uses the enhanced model (requires HD_TIER env var).
122
123	Returns:
124	SkillBundle containing the assembled SKILL.md and supporting files.
125
126	Raises:
127	RepoNotFoundError: If the repository does not exist or is private.
128	RateLimitError: If the GitHub API rate limit is exceeded.
129	"""
130	```
131
132	## README Updates
133
134	When shipping a feature, update the README if it changes:
135	- How to run the project locally
136	- A new environment variable that is required
137	- A new endpoint or behavior that users interact with
138
139	Do not update the README to describe implementation details — only what operators and users need to know.
140
141	## Common Rationalizations
142
143	\| Rationalization \| Reality \|
144	\|---\|---\|
145	\| "The code is self-documenting" \| Code explains what. Documentation explains why. Both are needed. \|
146	\| "We'll document it later" \| There is no later. The decision context is freshest right now. \|
147	\| "ADRs are too formal for a small project" \| The size of the project doesn't change the cost of re-litigating a decision 6 months later. \|
148	\| "I'll remember why we did this" \| You won't. Future-you and future-agents will thank present-you for writing it down. \|
149
150	## Red Flags
151
152	- Architectural decisions with no record of why alternatives were rejected
153	- "Obvious" design choices that turn out to be load-bearing constraints
154	- New en

People who liked this also viewed

6 picks

Type

documentation-and-adrs

32stars3forks

View on GitHub

How to install documentation-and-adrs?

jmxt3/gitscape.ai/documentation-and-adrs

$npx -y skills add jmxt3/gitscape.ai --skill documentation-and-adrs

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Documentation and Architecture Decision Records
2
3	## Overview
4
5	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.
6
7	## When to Use
8
9	- Making an architectural decision (choosing a library, pattern, or approach)
10	- Changing a public-facing API
11	- Adding a new feature that introduces a non-obvious constraint
12	- Resolving a significant technical debate
13	- Any decision that future agents or engineers would otherwise re-litigate
14
15	## Architecture Decision Records (ADRs)
16
17	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.
18
19	### ADR Location
20
21	```
22	.agents/decisions/
23	ADR-001-skill-assembly-approach.md
24	ADR-002-secret-management-gcp.md
25	ADR-003-file-preview-truncation.md
26	```
27
28	### ADR Template
29
30	```markdown
31	# ADR-[NNN]: [Short descriptive title]
32
33	Date: YYYY-MM-DD
34	Status: Proposed \| Accepted \| Superseded by ADR-[NNN]
35	Deciders: [Who was involved]
36
37	## Context
38
39	What situation or problem prompted this decision? Include constraints,
40	requirements, and any relevant background. Keep this to 1-3 paragraphs.
41
42	## Decision
43
44	The decision that was made. State it clearly and directly:
45	"We will use X because Y."
46
47	## Alternatives Considered
48
49	\| Alternative \| Why Rejected \|
50	\|---\|---\|
51	\| Option A \| Reason it was ruled out \|
52	\| Option B \| Reason it was ruled out \|
53
54	## Consequences
55
56	Positive:
57	- What becomes easier or possible
58
59	Negative / Trade-offs:
60	- What becomes harder or is given up
61
62	## See Also
63	- Link to related ADRs, docs, or issues
64	```
65
66	### ADR Examples for GitScape
67
68	```markdown
69	# ADR-001: Use Cloud Run for API Hosting
70
71	Date: 2026-06-01
72	Status: Accepted
73
74	## Context
75	GitScape's API is stateless — no database, no persistent file storage.
76	Requests process a GitHub repository and return a generated skill zip.
77
78	## Decision
79	Host the API on Cloud Run (fully managed) rather than GKE or GCE.
80
81	## Alternatives Considered
82	\| Alternative \| Why Rejected \|
83	\|---\|---\|
84	\| GKE \| Requires cluster management; no benefit for a stateless service \|
85	\| GCE \| Requires OS management; too much operational overhead \|
86	\| App Engine \| Less flexible for Python async workloads; Cloud Run preferred \|
87
88	## Consequences
89	Positive: Zero cluster management, scales to zero, pay-per-use.
90	Negative: Cold start latency (~1-2s) on first request after idle.
91	```
92
93	## Inline Code Documentation
94
95	### When to Write Comments
96
97	```python
98	# GOOD: Explains WHY, not WHAT
99	# GitHub's API rate-limits to 5000 requests/hour for authenticated users.
100	# We batch file fetches to minimize API calls during skill generation.
101	async def fetch_repo_files_batched(repo: str) -> list[File]:
102	...
103
104	# BAD: Explains WHAT (the code already does this)
105	# Loop through files and add to list
106	for f in files:
107	result.append(f)
108	```
109
110	### Docstrings
111
112	Write docstrings for all public functions in the API:
113
114	```python
115	async def generate_skill(repo: str, tier: str = "standard") -> SkillBundle:
116	"""Generate a skill bundle from a GitHub repository.
117
118	Args:
119	repo: GitHub repository in "owner/repo" format.
120	tier: Skill tier. "standard" uses the base model;
121	"hd" uses the enhanced model (requires HD_TIER env var).
122
123	Returns:
124	SkillBundle containing the assembled SKILL.md and supporting files.
125
126	Raises:
127	RepoNotFoundError: If the repository does not exist or is private.
128	RateLimitError: If the GitHub API rate limit is exceeded.
129	"""
130	```
131
132	## README Updates
133
134	When shipping a feature, update the README if it changes:
135	- How to run the project locally
136	- A new environment variable that is required
137	- A new endpoint or behavior that users interact with
138
139	Do not update the README to describe implementation details — only what operators and users need to know.
140
141	## Common Rationalizations
142
143	\| Rationalization \| Reality \|
144	\|---\|---\|
145	\| "The code is self-documenting" \| Code explains what. Documentation explains why. Both are needed. \|
146	\| "We'll document it later" \| There is no later. The decision context is freshest right now. \|
147	\| "ADRs are too formal for a small project" \| The size of the project doesn't change the cost of re-litigating a decision 6 months later. \|
148	\| "I'll remember why we did this" \| You won't. Future-you and future-agents will thank present-you for writing it down. \|
149
150	## Red Flags
151
152	- Architectural decisions with no record of why alternatives were rejected
153	- "Obvious" design choices that turn out to be load-bearing constraints
154	- New en

People who liked this also viewed

6 picks

Type