[PR #2245] [MERGED] docs: define performance priorities for analysis workflows #5111

New issue

Closed

opened 2026-10-31 01:04:03 +00:00 by bsakaguchi · 0 comments

bsakaguchi commented

2026-10-31 01:04:03 +00:00

Owner

📋 Pull Request Information

Original PR: https://github.com/morluto/rea/pull/2245
Author: @N0zoM1z0
Created: 10/12/2026
Status: ✅ Merged
Merged: 10/12/2026
Merged by: @N0zoM1z0

Base: main ← Head: docs/performance-policy

📝 Commits (1)

6b961f5 docs: define performance priorities for analysis workflows

📊 Changes

3 files changed (+36 additions, -4 deletions)

View changed files

📝 AGENTS.md (+25 -0)
📝 CONTRIBUTING.md (+5 -0)
📝 docs/tool-design.md (+6 -4)

📄 Description

Summary

Define performance requirements for REA analysis workflows and agent interfaces from the first implementation. Refs #2016.

Problem and expected behavior

Contributor guidance lacks an explicit performance order. Optimize agent tokens and returned context first, analysis time second, and CPU/memory third. Correctness, useful answers, Evidence provenance, caller choices, compatibility and resource safety remain requirements.

Change and scope

AGENTS.md: own the priorities, task-wide accounting, cache validity/freshness, resource bounds and measurement requirements.
CONTRIBUTING.md: link to that policy and request relevant review evidence.
docs/tool-design.md: return requested facts and necessary provenance inline; allow supported selection, summaries and views while preserving complete source Evidence, existing contracts and requested detail.

Contract and boundary impact

Documentation policy within existing contribution scope; an advance maintainer scope decision is not applicable. Runtime behavior, tool defaults, schemas, provider authority and generated metadata are unchanged. Existing confidence, coverage and limitation requirements are preserved.

Documentation or usability only; no target interaction.

Evidence and regression coverage

Reviewed against the retained-analysis summary/detail contract and analysis-efficiency experiments. The policy counts whole tasks, including schemas, extra calls and retries, and distinguishes tokens from serialized bytes. It permits labeled estimates and explicitly unmeasured costs.

Validation performed

Exact-file oxfmt --check --threads=2: passed.
git diff --check: passed.
npm run docs:check: passed; six build/check tasks and two README consistency tests.
npm run docs:build: passed.
New contributor link: checked relative target and unique Performance H2 rendered by GitHub GFM.

Checks used two CPUs with process-family memory monitoring. Highest sampled family RSS was approximately 2.37 GiB. New real-provider runs and performance benchmarks are not applicable to this prose-only change.

Compatibility, safety, and release

No migration or package metadata change. Do not treat the priority order as permission to discard required Evidence, silently truncate results, weaken resource safety or change complete defaults.

Before merge

Concrete, agreed enhancement with one focused outcome.
Scope and authority are resolved.
Owning documentation is updated.
Final diff reviewed for unrelated changes, secrets and unsupported claims.
Required CI passes on the final PR head.

CI passed on 6b961f5017ceb3951a3f6225224ece6374d034b0: run 38278863781, six successful checks and nineteen scope-based skips. The automatic Codex review did not run because the repository review quota is exhausted; final diff review and the checks listed above are the verification basis.

_{🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.}

## 📋 Pull Request Information **Original PR:** https://github.com/morluto/rea/pull/2245 **Author:** [@N0zoM1z0](https://github.com/N0zoM1z0) **Created:** 10/12/2026 **Status:** ✅ Merged **Merged:** 10/12/2026 **Merged by:** [@N0zoM1z0](https://github.com/N0zoM1z0) **Base:** `main` ← **Head:** `docs/performance-policy` --- ### 📝 Commits (1) - [`6b961f5`](https://github.com/morluto/rea/commit/6b961f5017ceb3951a3f6225224ece6374d034b0) docs: define performance priorities for analysis workflows ### 📊 Changes **3 files changed** (+36 additions, -4 deletions) <details> <summary>View changed files</summary> 📝 `AGENTS.md` (+25 -0) 📝 `CONTRIBUTING.md` (+5 -0) 📝 `docs/tool-design.md` (+6 -4) </details> ### 📄 Description ## Summary Define performance requirements for REA analysis workflows and agent interfaces from the first implementation. Refs #2016. ## Problem and expected behavior Contributor guidance lacks an explicit performance order. Optimize agent tokens and returned context first, analysis time second, and CPU/memory third. Correctness, useful answers, Evidence provenance, caller choices, compatibility and resource safety remain requirements. ## Change and scope - `AGENTS.md`: own the priorities, task-wide accounting, cache validity/freshness, resource bounds and measurement requirements. - `CONTRIBUTING.md`: link to that policy and request relevant review evidence. - `docs/tool-design.md`: return requested facts and necessary provenance inline; allow supported selection, summaries and views while preserving complete source Evidence, existing contracts and requested detail. ## Contract and boundary impact Documentation policy within existing contribution scope; an advance maintainer scope decision is not applicable. Runtime behavior, tool defaults, schemas, provider authority and generated metadata are unchanged. Existing confidence, coverage and limitation requirements are preserved. - [x] Documentation or usability only; no target interaction. ## Evidence and regression coverage Reviewed against the retained-analysis summary/detail contract and analysis-efficiency experiments. The policy counts whole tasks, including schemas, extra calls and retries, and distinguishes tokens from serialized bytes. It permits labeled estimates and explicitly unmeasured costs. ## Validation performed - Exact-file `oxfmt --check --threads=2`: passed. - `git diff --check`: passed. - `npm run docs:check`: passed; six build/check tasks and two README consistency tests. - `npm run docs:build`: passed. - New contributor link: checked relative target and unique `Performance` H2 rendered by GitHub GFM. Checks used two CPUs with process-family memory monitoring. Highest sampled family RSS was approximately 2.37 GiB. New real-provider runs and performance benchmarks are not applicable to this prose-only change. ## Compatibility, safety, and release No migration or package metadata change. Do not treat the priority order as permission to discard required Evidence, silently truncate results, weaken resource safety or change complete defaults. ## Before merge - [x] Concrete, agreed enhancement with one focused outcome. - [x] Scope and authority are resolved. - [x] Owning documentation is updated. - [x] Final diff reviewed for unrelated changes, secrets and unsupported claims. - [x] Required CI passes on the final PR head. CI passed on `6b961f5017ceb3951a3f6225224ece6374d034b0`: [run 38278863781](https://github.com/morluto/rea/actions/runs/38278863781), six successful checks and nineteen scope-based skips. The automatic Codex review did not run because the repository review quota is exhausted; final diff review and the checks listed above are the verification basis. --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>

bsakaguchi

2026-10-31 01:04:03 +00:00