aws-samples / aws-samples/sample-autonomous-cloud-coding-agents

docs(governance): refine ADR-012 to many-to-many ADR↔Persona↔Skill graph with bidirectional backlinks + parity linter

Open
#381 2 comments 0 reactions 0 assignees View on GitHub
documentation enhancement governance
Dominant language
TypeScript
Stars
143
Forks
46
Avg merge
3d 9h
Merged PRs (30d)
20

Description

## Summary

Refine ADR-012's operational-knowledge model from a strict **upward tree** (Skill → Guide → ADR) into a **many-to-many graph** with **Persona** as a first-class node, enforced by **bidirectional frontmatter backlinks** and a **parity linter** in CI. This makes downstream artifacts (personas, skills) detectably-in-sync with their parent ADRs without a full-repository semantic read — directly mitigating the staleness risk ADR-012 itself flags but does not solve.

> Refinement, not reversal (per #380 boundary test): the three-layer ADR→Guide→Skill **decision stands**; we are extending the "Reference direction" section. This is intended as the **first real exercise** of the in-place refinement path introduced by #380 — ADR-012 is edited in place with a `## Changelog` entry, not superseded.

## Motivation

ADR-012 §"Reference direction" asserts references point **upward only** in a tree. Real usage breaks the tree:

1. **One ADR → many personas** — ADR-003 shapes Planner, Implementor, Reviewer, **and** Administrator.
2. **One persona → many ADRs** — Administrator is shaped by ADR-003, ADR-009, and the security-triage ADR (#277/ADR-016).
3. **One skill → many personas** — shared skills (e.g. `validate-dependencies`) serve Implementor **and** Planner.

ADR-012 lists this as an unmitigated risk: *"(!) Reference chain integrity must be maintained — a broken link between layers means drift goes undetected."* This issue mitigates it mechanically.

## Decision to encode (graph + invariant)

```
ADR (decision) ──affects──▶ Persona ──exercises──▶ Skill
▲ many-to-many ▲ │ many-to-many │ │
└────────────────┴──────────┴──────────────┴─ optional direct Skill→ADR
```

- **Persona** becomes a first-class node (e.g. Administrator, PR Reviewer, Issue Triager, Implementor, Planner), living under a documented home (`docs/personas/` and/or the plugin `agents/` dir — to be decided in design).
- **Edges are declared in frontmatter on both endpoints**, e.g.:
- ADR: `personas: [planner, implementor, reviewer, administrator]`
- Persona: `adrs: [ADR-003, ADR-008]`, `skills: [pickup-issue, validate-dependencies]`
- Skill: `adrs: [ADR-003]` (or explicit `adrs: []` for intentionally standalone), `personas: [implementor]`, `guide: CONTRIBUTOR_WORKFLOW.md`
- **Invariant (parity linter):** every declared edge MUST be reciprocated on the other endpoint. A one-directional edge fails CI. A skill with no ADR parent MUST declare `adrs: []` explicitly (deliberate, not an oversight).
- **Maturity is derived, not stored:** do NOT add "operationalized / enforced / validated" status fields to ADRs (they rot — cf. ADR-003's `Implemented/Planned` enforcement column). Compute maturity by walking the graph: operationalized iff ≥1 persona references it; enforced iff a skill/hook implements it.

## Honest boundary (tabula-rasa / ADR-010)

The parity linter verifies **structural** consistency (links resolve and reciprocate; supersede flags surface dependents for review) — **not semantic freshness** (that the skill still reflects the ADR's intent). State this limit explicitly in the ADR so the standard doesn't over-promise. Semantic freshness remains a human/agent judgment.

## Deliverables

- [ ] Amend ADR-012 §"Reference direction" in place: many-to-many graph, Persona as first-class node, bidirectional edges; add a `## Changelog` entry + bump `Last-updated` (uses #380 mechanics).
- [ ] Define the frontmatter edge schema for ADR / Persona / Skill (and where personas live).
- [ ] Specify the parity-linter contract (inputs, the reciprocity invariant, failure output) — implementation may be a follow-up.
- [ ] Document the supersede interaction: when an ADR goes `superseded`, the linter flags all referencing personas/skills for review.
- [ ] Sync Starlight mirror for ADR-012; commit alongside source.

## Acceptance criteria

- [ ] ADR-012 expresses ADR↔Persona↔Skill as a many-to-many graph with reciprocal edges; the old "upward tree only" wording is replaced and a changelog entry records the refinement.
- [ ] The frontmatter schema is precise enough that a linter can be written from the ADR alone.
- [ ] The structural-vs-semantic limit is stated explicitly.
- [ ] No implementation-maturity status fields are added to any ADR.

## Dependencies

- **Blocked by #380** (in-place refinement must be a sanctioned operation before ADR-012 can be edited in place rather than superseded).
- Related: #186 (ADR-003 decomposition produces the first personas/skills this graph will bind); #254 (mechanical module-boundary enforcement — same "graph integrity as CI gate" technique, prior art); #246 (agent asset registry — overlaps on skill/capability cataloguing; reconcile).

## References

- ADR-012 §"Reference direction", §Consequences (the `(!)` integrity risk this resolves)
- #380 — refine-in-place standard (prerequisite)
- #246, #254 — related registry / boundary-enforcement work

---

*Filed under contribution governance (ADR-003). No implementation/file edits until `approved` + assigned.*

Contributor guide

Open the contributing guide

Research direction

Read ADR-012's “Reference direction” and “Consequences” sections, then review #380 for the sanctioned in-place refinement mechanics. Define the ADR, Persona, and Skill frontmatter schema, parity-linter contract, supersede behavior, and Starlight mirror update; done means the acceptance criteria are documented and the source and mirror agree.

Written by the indexing model from the issue text.

Assessment

Domain
documentation
Issue type
Documentation
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.