Rename RFCs to Agent Notes
This commit is contained in:
@@ -45,7 +45,7 @@ This is not a one-way shortening pass. Add or restore prose when code, types, an
|
||||
- **Tests:** explain only non-obvious test design—why a fixture, assertion, platform accommodation, real entry path, or indirect observation is necessary. Delete walkthroughs and inventories.
|
||||
- **Cookbooks:** include prerequisites, required actions, the real entry path, observable verification, and concise warnings.
|
||||
- **READMEs:** include the consumer contract: configuration, semantics, failures, limitations, extension points, and model-visible effects. Quote stable model-visible text owned by the package; link generated catalogs and cross-package owners. Keep durable gaps and maintainer traps, not ordinary cleanup inventories. Follow the [package README contract](../../../docs/cookbook/adding-a-package.md#4-write-the-package-readme).
|
||||
- **RFCs:** retain unique rationale, mechanisms, alternatives, consequences, shipped verification contracts, and named coverage gaps. Implemented RFCs state shipped reality in the present tense; remove planning checklists, not evidence of what pins the decision.
|
||||
- **Agent Notes:** retain unique rationale, mechanisms, alternatives, consequences, shipped verification contracts, and named coverage gaps. Implemented Agent Notes state shipped reality in the present tense; remove planning checklists, not evidence of what pins the decision.
|
||||
- **Postmortems:** retain the incident sequence, evidence, causal chain, impact, and prevention. Remove repeated persuasion or implementation detail that does not establish causality.
|
||||
- **Skills and agent instructions:** state behavioral guardrails and explicit scope limitations such as “guidance, not a script/checklist.” Keep the workflow concise and link its source of truth.
|
||||
- **Examples and configuration comments:** explain boundaries, non-obvious wiring or load order, security stance, replay behavior, exceptions, and likely misuse. Do not narrate entries that the configuration already shows.
|
||||
|
||||
@@ -56,7 +56,7 @@ Event order and its current-request consequence are caller-visible behavior, not
|
||||
|
||||
**Over-trimmed:** “Worker realm support.”
|
||||
|
||||
**Balanced:** “Owns the worker realm and its host bridge. Realm initialization is single-shot; disposal terminates the worker and rejects later calls. See the worker-isolation RFC for the protocol rationale.”
|
||||
**Balanced:** “Owns the worker realm and its host bridge. Realm initialization is single-shot; disposal terminates the worker and rejects later calls. See the worker-isolation Agent Note for the protocol rationale.”
|
||||
|
||||
**Over-detailed:** A paragraph-by-paragraph preview of the classes and helper functions below.
|
||||
|
||||
@@ -84,17 +84,17 @@ Keep mapping details that explain an abstraction boundary or intentional informa
|
||||
|
||||
## Link rationale while keeping the local contract
|
||||
|
||||
**Over-trimmed:** “Disposal is documented in the lifecycle RFC.”
|
||||
**Over-trimmed:** “Disposal is documented in the lifecycle Agent Note.”
|
||||
|
||||
**Balanced:** “Disposal aborts the run and waits for provider quiescence. See the lifecycle RFC for ownership and race handling.”
|
||||
**Balanced:** “Disposal aborts the run and waits for provider quiescence. See the lifecycle Agent Note for ownership and race handling.”
|
||||
|
||||
**Over-detailed:** Repeating the RFC's promise choreography and rejected ownership models beside every disposer.
|
||||
**Over-detailed:** Repeating the Agent Note's promise choreography and rejected ownership models beside every disposer.
|
||||
|
||||
Keep the behavior and completion guarantee where callers need them. Link aggressively for the algorithm and rationale; a link cannot replace the local contract.
|
||||
|
||||
## Implemented RFCs retain verification contracts
|
||||
## Implemented Agent Notes retain verification contracts
|
||||
|
||||
**Over-trimmed:** Deleting the entire Testing section because the RFC has already shipped.
|
||||
**Over-trimmed:** Deleting the entire Testing section because the Agent Note has already shipped.
|
||||
|
||||
**Balanced:** “Unit tests cover cancellation before and after publication, disposal quiescence, and provider reload. A built-entry smoke covers the real loader path; snapshot coverage is deferred because the transport is process-specific.”
|
||||
|
||||
@@ -162,6 +162,6 @@ Know what the generator extracts. That fragment must preserve the contract neede
|
||||
|
||||
**Over-detailed:** Listing private helper cleanup and unused test-only accessors with no caller or maintainer consequence.
|
||||
|
||||
**Balanced:** “Provider selection is cached for the plugin lifetime; installing or repairing a provider requires reload.” Keep ordinary cleanup in its TODO or RFC.
|
||||
**Balanced:** “Provider selection is cached for the plugin lifetime; installing or repairing a provider requires reload.” Keep ordinary cleanup in its TODO or Agent Note.
|
||||
|
||||
Retain gaps and non-obvious constraints that affect use or safe maintenance. A package README is not a backlog dump.
|
||||
|
||||
Reference in New Issue
Block a user