From 97ed8d6375975a666254a1d642582ef4efccd985 Mon Sep 17 00:00:00 2001 From: Nishiki Liu Date: Fri, 30 Oct 2026 08:57:41 -0700 Subject: [PATCH] docs(agents): reinforcement (week of 2026-10-30) --- CONTRIBUTING.md | 4 ++++ docs/documentation-conventions.md | 10 +++++++++- docs/testing-and-review.md | 10 ++++++++++ hub/docs/coding-conventions.md | 5 +++++ 4 files changed, 28 insertions(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 84f75c5b..03870d9b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -150,6 +150,10 @@ For Hub or canvas UI changes, finish the PR description with screenshots of ever Still run the relevant checks before opening the PR. Mention only known verification gaps that affect the change, such as a required check that could not run or behavior that remains unverified. Describe the actual gap, not whether the agent drafting the description ran tests itself. +### Stacked pull requests + +For stacked PRs, use GitHub's built-in stacked PR feature. Setting each PR's base to another PR's branch does not create a native stack by itself. Check that GitHub shows the PRs as a stack. + ## Pull request review Maintainers may ask for revisions before merging. Contributions are reviewed for correctness, fit with the project's direction, and ongoing maintenance needs. Not every proposal or pull request will be accepted. diff --git a/docs/documentation-conventions.md b/docs/documentation-conventions.md index 34d6822b..df4d255c 100644 --- a/docs/documentation-conventions.md +++ b/docs/documentation-conventions.md @@ -12,6 +12,12 @@ These conventions apply across Replica, including documentation, pull request de - Avoid repeating known context. - Ask one focused question when the answer changes product behavior or prevents costly rework. +### Answer the current question + +For a specific design question, recommend an option and explain its benefits and costs. Ask a question only when the answer would change the decision. Save function lists and other implementation details for implementation discussions. + +For example, write: “Send live comment updates only to people who still have access. After reconnecting, load the current comments instead of replaying missed updates. This avoids storing a separate notification history.” + ## Plain language - Name the person or system performing the action. @@ -37,7 +43,7 @@ Prefer concrete wording: ## Product and design discussions -State the product contract before proposing implementation details: +Before discussing implementation, agree on the feature requirements: 1. Name the person or system using the feature. 2. State the outcome they need. @@ -45,6 +51,8 @@ State the product contract before proposing implementation details: 4. Explain how access or state begins and ends. 5. Name the first version's non-goals. +Once these requirements are agreed upon, keep following them without listing them in every reply. Answer the current question without adding unrelated requirements. Explain access rules, failures, and recovery when they affect the decision. + Label accepted requirements and proposed implementation choices separately. Do not present one possible mechanism as technically necessary. When a security boundary has several valid designs, explain the risk being controlled and why the proposed boundary is the simplest fit. Use the accepted product name consistently. Remove rejected terminology and plans instead of leaving contradictory guidance in the same document. diff --git a/docs/testing-and-review.md b/docs/testing-and-review.md index 4cc47afd..f6107b9a 100644 --- a/docs/testing-and-review.md +++ b/docs/testing-and-review.md @@ -18,6 +18,16 @@ Use the [test-writing skill](../.github/skills/write-tests/SKILL.md) when adding Start with the intended behavior and the regression a test should catch. Inspect existing coverage before adding cases. Each case should protect a distinct outcome, boundary, or failure mode through the smallest useful public interface. An existing case that already catches the regression usually needs an update rather than another test. +Cover successful use and failures that could break access rules, lose data, prevent recovery, or cause other serious problems. A different possible failure does not always need another test. Keep coverage for serious security and data-loss risks even when they are rare. + +Do not add tests only to prove that: + +- A dependency's own input validation works. +- A helper can be imported. +- A function moved to another file. + +Test an extracted helper through its caller when that already covers its important behavior. Before finishing, look for missing important cases as well as unnecessary ones. When combining cases, keep coverage for each supported kind of input. Fewer tests alone do not mean better tests. + Choose assertions that survive an equivalent implementation. Check outcomes such as saved state, returned data, navigation, access decisions, and usable controls. Exact protocol values, serialization, accessible names, meaningful state mappings, and safety restrictions can be contracts worth asserting. Ordinary copy, icon counts, internal markup, and whole configuration snapshots usually are not. A text query that identifies a control is different from a test whose only purpose is freezing its wording. For agent instructions, distinguish discoverable metadata and required safety guidance from incidental phrasing; phrase presence alone does not prove agent behavior. Use human review for visual appearance, supported by relevant screenshots or recordings in pull requests with meaningful UI changes. Do not freeze colors, spacing, typography, icon pixels, or cosmetic CSS structure in automated assertions. Test behavior and accessibility instead. Geometry that defines functional data, such as a captured selection's bounds, is different from checking rendered styling. diff --git a/hub/docs/coding-conventions.md b/hub/docs/coding-conventions.md index 3e400881..0b900182 100644 --- a/hub/docs/coding-conventions.md +++ b/hub/docs/coding-conventions.md @@ -48,6 +48,11 @@ components, hooks, and utilities - Put each standalone function in a kebab-case directory with `index.ts` or `index.tsx`, its tests, types, and styles. - Export at most one function per file and import exact directories. - Do not create shared index files that only collect sibling exports. +- Keep `index.ts` focused on its function: + - Put schemas and constants declared outside functions in `constants.ts` beside `index.ts`. + - Put types declared outside functions in `types.ts` beside `index.ts`. + - Keep values and types that depend on function arguments or type parameters inside that function. + - Put constants shared by a domain in that domain's directory. Do not create a function directory just to hold constants. - Rails TSX page views adapt Superglue data and browser workflows into their one presentation Page. - Discover Rails TSX page views from their virtual paths instead of maintaining a parallel mapping. - Group package, alias, and relative imports separately.