Skip to content

docs: route learning capture through editable source owners #808

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
ss-o merged 1 commit into from
Oct 16, 2026
Merged

docs: route learning capture through editable source owners #808

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
39 changes: 24 additions & 15 deletions knowledge/domains/governance/learning-capture.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -51,24 +51,29 @@ satisfy the workflow.

## Destination matrix

| Finding | Preferred owner |
| ------------------------------------------------------------- | ------------------------------------------------------------------------------ |
| A recurrence that can be detected mechanically | Code, test, type, schema, lint rule, validator, or script |
| A mandatory rule that applies broadly | Root `AGENTS.md` |
| Mandatory detail limited by task or path | Routed scoped instruction |
| A reusable multi-step agent workflow | Skill |
| An implementation idiom observed in at least two repositories | `PATTERNS.md` |
| A significant or difficult-to-reverse decision | Proposed ADR |
| A repeatable operational procedure | Runbook |
| Active work, blocker, or deferred work | Owning GitHub issue or pull request, plus a linked Linear mirror when required |
| An unfinished session another agent must resume | GitHub-native agent handoff |
| Durable long-form user or maintainer guidance | Appropriate documentation or wiki area |
| A private maintainer preference or private heuristic | Private memory, with explicit maintainer request or consent |
| A one-time detail already clear from code or history | No additional artifact |
Resolve a generated destination through [knowledge delivery](../../delivery.json) before editing: its declared `knowledge/domains/` source is editable, not the generated consumer. For approved project-native instructions, consult [project delivery](../../project-delivery.json) and follow [knowledge maintenance](../agents/knowledge-maintenance.md); a draft source does not replace the project's current owner before publication, approval and delivery checks pass. Unmigrated content retains its existing owner.

| Finding | Preferred owner |
| ------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
| A recurrence that can be detected mechanically | Code, test, type, schema, lint rule, validator, or script |
| A mandatory rule that applies broadly | `knowledge/domains/agents/organization-policy.md`, which generates `AGENTS.md` |
| Mandatory detail limited by task or path | The declared source of the routed scoped instruction |
| A reusable multi-step agent workflow | Skill |
| An implementation idiom observed in at least two repositories | `knowledge/domains/agents/implementation-patterns.md`, which generates `PATTERNS.md` |
| A significant or difficult-to-reverse decision | Proposed ADR |
| A repeatable operational procedure | The declared source of the maintained runbook |
| Active work, blocker, or deferred work | Owning GitHub issue or pull request, plus a linked Linear mirror when required |
| An unfinished session another agent must resume | GitHub-native agent handoff |
| Durable long-form user or maintainer guidance | Appropriate documentation or wiki area |
| A private maintainer preference or private heuristic | Private memory, with explicit maintainer request or consent |
| A candidate awaiting evidence or authority | Provisional local finding naming the proposed canonical owner |
| A one-time detail already clear from code or history | No additional artifact |

Prefer executable prevention over prose. Extend an existing canonical owner
instead of creating a second source of truth.

Local workspace notes are provisional capture, not durable promotion. Link a useful finding to its canonical correction or owning issue when authorized, and reconcile the note against that evidence. A note's existence or a session's completion claim does not establish that the underlying problem is fixed; retain unresolved parts of a multi-part finding.

## Candidate quality gate

A candidate is ready for promotion only when all of these are true:
Expand All @@ -85,6 +90,8 @@ A candidate is ready for promotion only when all of these are true:

If any item is missing, keep the result as a candidate or discard it.

Give each useful candidate a disposition in the existing task, issue or pull-request evidence: applied locally with paths and checks, promoted with the canonical artifact, tracked with an owning record, proposed with the missing authority, or declined with a reason. An uncommitted edit is applied locally, not published guidance. This does not require a new artifact for `No durable learning`, which remains internal unless an audit trail is requested.

## Authority and privacy gate

- Do not write private memory unless the maintainer explicitly requested it or
Expand All @@ -109,7 +116,7 @@ When a candidate matters, include a concise completion note:
Learning candidate: <finding>
Evidence: <specific evidence>
Proposed owner: <canonical artifact>
Status: promoted | recorded for follow-up | approval required
Status: applied locally | promoted | recorded for follow-up | approval required | declined
```

A final response or handoff is not a durable owner by itself. When authority is
Expand All @@ -132,6 +139,8 @@ first. Measure:
- median review overhead
- stale or contradictory artifacts introduced

Use retained evidence and state the reviewed scope. A missing evaluation record is an evidence gap, not an observed zero or proof that no review occurred. Keep unreviewed tasks and unknown outcomes distinct from `No durable learning`; record any outstanding evaluation under its owning work item rather than inferring results.

Do not add a command hook merely because one review was missed. Consider a
runtime reminder only when the measured omission rate exceeds 10 percent and a
prototype can keep false reminders below 10 percent without parsing an
Expand Down
39 changes: 24 additions & 15 deletions runbooks/learning-capture.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -55,24 +55,29 @@ satisfy the workflow.

## Destination matrix

| Finding | Preferred owner |
| ------------------------------------------------------------- | ------------------------------------------------------------------------------ |
| A recurrence that can be detected mechanically | Code, test, type, schema, lint rule, validator, or script |
| A mandatory rule that applies broadly | Root `AGENTS.md` |
| Mandatory detail limited by task or path | Routed scoped instruction |
| A reusable multi-step agent workflow | Skill |
| An implementation idiom observed in at least two repositories | `PATTERNS.md` |
| A significant or difficult-to-reverse decision | Proposed ADR |
| A repeatable operational procedure | Runbook |
| Active work, blocker, or deferred work | Owning GitHub issue or pull request, plus a linked Linear mirror when required |
| An unfinished session another agent must resume | GitHub-native agent handoff |
| Durable long-form user or maintainer guidance | Appropriate documentation or wiki area |
| A private maintainer preference or private heuristic | Private memory, with explicit maintainer request or consent |
| A one-time detail already clear from code or history | No additional artifact |
Resolve a generated destination through [knowledge delivery](../knowledge/delivery.json) before editing: its declared `knowledge/domains/` source is editable, not the generated consumer. For approved project-native instructions, consult [project delivery](../knowledge/project-delivery.json) and follow [knowledge maintenance](../knowledge/domains/agents/knowledge-maintenance.md); a draft source does not replace the project's current owner before publication, approval and delivery checks pass. Unmigrated content retains its existing owner.

| Finding | Preferred owner |
| ------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
| A recurrence that can be detected mechanically | Code, test, type, schema, lint rule, validator, or script |
| A mandatory rule that applies broadly | `knowledge/domains/agents/organization-policy.md`, which generates `AGENTS.md` |
| Mandatory detail limited by task or path | The declared source of the routed scoped instruction |
| A reusable multi-step agent workflow | Skill |
| An implementation idiom observed in at least two repositories | `knowledge/domains/agents/implementation-patterns.md`, which generates `PATTERNS.md` |
| A significant or difficult-to-reverse decision | Proposed ADR |
| A repeatable operational procedure | The declared source of the maintained runbook |
| Active work, blocker, or deferred work | Owning GitHub issue or pull request, plus a linked Linear mirror when required |
| An unfinished session another agent must resume | GitHub-native agent handoff |
| Durable long-form user or maintainer guidance | Appropriate documentation or wiki area |
| A private maintainer preference or private heuristic | Private memory, with explicit maintainer request or consent |
| A candidate awaiting evidence or authority | Provisional local finding naming the proposed canonical owner |
| A one-time detail already clear from code or history | No additional artifact |

Prefer executable prevention over prose. Extend an existing canonical owner
instead of creating a second source of truth.

Local workspace notes are provisional capture, not durable promotion. Link a useful finding to its canonical correction or owning issue when authorized, and reconcile the note against that evidence. A note's existence or a session's completion claim does not establish that the underlying problem is fixed; retain unresolved parts of a multi-part finding.

## Candidate quality gate

A candidate is ready for promotion only when all of these are true:
Expand All @@ -89,6 +94,8 @@ A candidate is ready for promotion only when all of these are true:

If any item is missing, keep the result as a candidate or discard it.

Give each useful candidate a disposition in the existing task, issue or pull-request evidence: applied locally with paths and checks, promoted with the canonical artifact, tracked with an owning record, proposed with the missing authority, or declined with a reason. An uncommitted edit is applied locally, not published guidance. This does not require a new artifact for `No durable learning`, which remains internal unless an audit trail is requested.

## Authority and privacy gate

- Do not write private memory unless the maintainer explicitly requested it or
Expand All @@ -113,7 +120,7 @@ When a candidate matters, include a concise completion note:
Learning candidate: <finding>
Evidence: <specific evidence>
Proposed owner: <canonical artifact>
Status: promoted | recorded for follow-up | approval required
Status: applied locally | promoted | recorded for follow-up | approval required | declined
```

A final response or handoff is not a durable owner by itself. When authority is
Expand All @@ -136,6 +143,8 @@ first. Measure:
- median review overhead
- stale or contradictory artifacts introduced

Use retained evidence and state the reviewed scope. A missing evaluation record is an evidence gap, not an observed zero or proof that no review occurred. Keep unreviewed tasks and unknown outcomes distinct from `No durable learning`; record any outstanding evaluation under its owning work item rather than inferring results.

Do not add a command hook merely because one review was missed. Consider a
runtime reminder only when the measured omission rate exceeds 10 percent and a
prototype can keep false reminders below 10 percent without parsing an
Expand Down
Loading