Skip to content

Commit cfa51b2

Browse files
KooshaPariKooshaPari
committed
docs: add git-backed documentation governance scaffold
1 parent 0fdb88f commit cfa51b2

13 files changed

Lines changed: 217 additions & 0 deletions

‎docs/README.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -73,3 +73,10 @@ docs/
7373
- Factory Droids: https://factory.ai/news/ga
7474
- SDD Research: arXiv:2602.00180
7575
- AWS AutoPilot: Self-driving DevOps patterns
76+
77+
## Governance
78+
79+
- [Stacked PRs and Release Channels](./context/governance/STACKED_PRS_AND_RELEASE_CHANNELS.md)
80+
- [Stacked PR Bookset](./context/governance/bookset/README.md)
81+
- [Git-Backed Documentation](./context/governance/git-backed-documentation/README.md)
82+

‎docs/context/governance/git-backed-documentation/README.md‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
# Git-Backed Documentation Framework
2+
3+
This framework makes PR-ready docs reproducible and review-friendly before coding starts.
4+
5+
## Order of Work (required)
6+
1. `ADR` first: capture problem framing and decision boundaries.
7+
2. `PRD` next: define scope, success criteria, and acceptance.
8+
3. `FRs` then: decompose requirements into implementable packages.
9+
4. `Plan` after FRs: batch execution sequence, dependencies, owners.
10+
5. `Tests` before/alongside implementation: unit/integration/behavior coverage.
11+
12+
## Commit Batches
13+
- **Batch A**: scaffolding + templates + ADR + PRD
14+
- **Batch B**: FR docs + plan and dependency graph
15+
- **Batch C**: test plan + execution + implementation-ready checklist
16+
17+
## Hard Rules
18+
- One branch per active PR stack only.
19+
- One batch per commit unless dependency forces a split.
20+
- Target branch changes must be `main` descendants and pushed before PR creation.
21+
- Any file >125 lines in this framework must be split before merge.
22+
23+
## Required Branch State
24+
- Branch has upstream tracking.
25+
- No unpushed commits on the source branch.
26+
- Local branch sync is verified in CI before PR creation.
27+
- Run this check before opening PRs:
28+
29+
```bash
30+
git fetch
31+
if git status --short --branch | rg -q "ahead"; then
32+
echo "FAIL: source branch is ahead of upstream"
33+
exit 1
34+
fi
35+
```

‎docs/context/governance/git-backed-documentation/adr/ADR-0001-internal-elicitation.md‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
# ADR-0001: Internal Elicitation Primitive First
2+
3+
## Context
4+
Documenting intent before implementation reduces divergence and bot-replay failures.
5+
6+
## Decision
7+
Capture elicitation questions in `ADR-0002` before opening feature PRs.
8+
9+
## Outcome
10+
- Reuse across repos via this template set.
11+
- Enforces same order before PR stack creation.

‎docs/context/governance/git-backed-documentation/fr/FR-0001-documentation-stubs.md‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
# FR-0001: Documentation Stubs
2+
3+
## Requirement
4+
Each feature PR requires docs with linked ADR/PRD/FR/Plan/Test files.
5+
6+
## Acceptance
7+
- Scaffold created in new branch.
8+
- Files are under 125 lines until promoted.
9+
- Cross-references are present in README.

‎docs/context/governance/git-backed-documentation/plan/PLAN-0001-docs-batching.md‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
# PLAN-0001: Git-Backed Docs Batching
2+
3+
## Stage 0
4+
- Validate branch has upstream and no unpushed commits.
5+
6+
## Stage 1
7+
- Create template and stub files.
8+
9+
## Stage 2
10+
- Add links in docs entrypoints.
11+
12+
## Stage 3
13+
- Run smoke checks and finalize.

‎docs/context/governance/git-backed-documentation/prd/PRD-0001-git-backed-documentation.md‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
# PRD-0001: Git-Backed Documentation Baseline
2+
3+
## Scope
4+
Enable all active repos to start feature work from consistent ADR/PRD/FR/Plan/Test templates.
5+
6+
## Success Criteria
7+
- Templates exist in `docs/context/governance/git-backed-documentation/`.
8+
- README references are discoverable from docs entrypoint.
9+
- Each new requirement starts with ADR->PRD->FR->Plan order.

‎docs/context/governance/git-backed-documentation/templates/ADR_TEMPLATE.md‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
# ADR-000X: Title
2+
3+
## Context
4+
- Why are we doing this now?
5+
- What existing risk are we reducing?
6+
7+
## Decision
8+
- Decision:
9+
- Rejected alternatives:
10+
11+
## Consequences
12+
- Positive:
13+
- Negative:
14+
- Open questions:
15+
16+
## Commit/Batch Mapping
17+
- Batch target:
18+
- Files touched:
19+
- Dependencies:

‎docs/context/governance/git-backed-documentation/templates/FR_TEMPLATE.md‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
# FR-000X: Feature Requirement
2+
3+
## Requirement
4+
- Statement:
5+
6+
## Acceptance
7+
- Scenario:
8+
- Expected result:
9+
10+
## Constraints
11+
- Constraints:
12+
- Guardrails:
13+
14+
## Dependencies
15+
- Depends on:
16+
17+
## Files & APIs
18+
- Libraries/Modules:
19+
- New/updated APIs:

‎docs/context/governance/git-backed-documentation/templates/PLAN_TEMPLATE.md‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
# PLAN-000X: Execution Plan
2+
3+
## Phase
4+
1. Research and branch validation
5+
2. Documentation prep
6+
3. Implementation
7+
4. Test execution
8+
9+
## DAG
10+
- TaskID | Task | DependsOn
11+
- T1 | ADR complete | none
12+
- T2 | PRD complete | T1
13+
- T3 | FR set complete | T2
14+
- T4 | Plan split | T2
15+
16+
## Commit Batches
17+
- Batch 1: baseline docs
18+
- Batch 2: spec docs
19+
- Batch 3: tests and validation
20+
21+
## Rollback
22+
- Safe rollback point:
23+
- Reverse plan:

‎docs/context/governance/git-backed-documentation/templates/PRD_TEMPLATE.md‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
# PRD-000X: Title
2+
3+
## Problem
4+
- Current pain:
5+
- Who is affected:
6+
7+
## Scope
8+
- In scope:
9+
- Out of scope:
10+
11+
## Success Criteria
12+
- Measurable metric:
13+
- Completion signal:
14+
15+
## Risks
16+
- Technical:
17+
- Process:
18+
19+
## Non-Functional
20+
- Security:
21+
- Performance:
22+
- Maintainability:
23+
24+
## Pre-merge checks
25+
- ADR complete:
26+
- FR mapping complete:

0 commit comments

Comments
 (0)