Skip to content

knowledge: source a hand-off deliverable from the generator, not by hand (qa/deliverables) #18

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

Closed
dch0202-rsquare wants to merge 3 commits into from
Closed

knowledge: source a hand-off deliverable from the generator, not by hand (qa/deliverables) #18

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
cd5ba1b
knowledge: ingest 1 verified insight (qa/deliverables)
dch0202-rsquare Aug 4, 2026
d602c5c
docs: add cross-check note to ingest report
dch0202-rsquare Aug 4, 2026
7388bec
docs: add decision log to ingest report
dch0202-rsquare Aug 4, 2026
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
161 changes: 76 additions & 85 deletions .dev-loop/INGEST_REPORT.md
View file
Open in desktop

Large diffs are not rendered by default.

24 changes: 12 additions & 12 deletions INDEX.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,17 +7,17 @@ domain's `index.md`. Load nothing else at this level.
follow the cross-pointers in their index or take the next matching seeded domain
(routing protocol step 1, `AGENTS.md`).

| Domain | Status | Route here when |
|--------|--------|-----------------|
| [databases](wiki/databases/index.md) | **seeded** | Designing schemas/tables/keys, choosing or evaluating indexes, writing or optimizing queries, choosing transaction/isolation behavior |
| [backend](wiki/backend/index.md) | **seeded** | Server-side application code — language-agnostic (`common/`: API contracts, idempotency, JWT, timeouts/retries, caching, jobs, transactions in app code, shared state/pools, errors, LLM completion validation & context budgeting, consuming external-API responses, externally-owned defaults, object-storage references) plus stack subtrees: `java/` (JPA, Spring proxies, JVM threads/memory), `node/` (event loop, promises, runtime validation, shutdown), `python/` (GIL/asyncio, pydantic, WSGI/ASGI workers, language traps) |
| [frontend](wiki/frontend/index.md) | **seeded** | Web UI code: state placement, rendering performance, in-UI data fetching (races, infinite scroll), auth token handling, forms, XSS-safe output, accessibility |
| [infrastructure](wiki/infrastructure/index.md) | **seeded** | CI/CD pipelines, secrets in build/deploy, container image builds, rollout/rollback strategy, observability (logs/metrics/alerting) |
| [testing](wiki/testing/index.md) | **seeded** | Writing or structuring automated tests: level choice, cases/assertions, test data, mock decisions, flaky tests (release-process quality → qa) |
| [qa](wiki/qa/index.md) | **seeded** | Release-quality process: release gates, regression scoping, bug reports, severity/priority triage, exploratory testing, automated verification of document deliverables (spec/RFC gates) (writing automated test code → testing) |
| [debugging](wiki/debugging/index.md) | **seeded** | Diagnosing a failure — finding what is wrong and why: reproducing, bisection, hypothesis testing, traces/logs, intermittent failures (fixing the diagnosed fault → its owning domain) |
| [security](wiki/security/index.md) | **seeded** | Trust-boundary decisions: input validation, session-vs-token auth choice, per-resource authorization (IDOR), secrets hygiene, dependency trust, PII handling (XSS rendering → frontend; CI secrets → infrastructure; JWT implementation → backend/frontend auth) |
| [platforms](wiki/platforms/index.md) | **seeded** | OS-level differences breaking code across macOS/Linux/Windows: shell portability, BSD-vs-GNU CLI, filesystem case/line endings, Unicode normalization in text/file-name matching, commands inspected before execution, background services/cron, invoking prompt-capable CLIs non-interactively, toolchain version pinning |
| [mobile](wiki/mobile/index.md) | **seeded** | App-side iOS/Android/cross-platform: process death/state survival, offline-first sync, mobile-network calls, store rollout/hotfix strategy, startup time |
| Domain | Status | Route here when |
| ---------------------------------------------- | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [databases](wiki/databases/index.md) | **seeded** | Designing schemas/tables/keys, choosing or evaluating indexes, writing or optimizing queries, choosing transaction/isolation behavior |
| [backend](wiki/backend/index.md) | **seeded** | Server-side application code — language-agnostic (`common/`: API contracts, idempotency, JWT, timeouts/retries, caching, jobs, transactions in app code, shared state/pools, errors, LLM completion validation & context budgeting, consuming external-API responses, externally-owned defaults, object-storage references) plus stack subtrees: `java/` (JPA, Spring proxies, JVM threads/memory), `node/` (event loop, promises, runtime validation, shutdown), `python/` (GIL/asyncio, pydantic, WSGI/ASGI workers, language traps) |
| [frontend](wiki/frontend/index.md) | **seeded** | Web UI code: state placement, rendering performance, in-UI data fetching (races, infinite scroll), auth token handling, forms, XSS-safe output, accessibility |
| [infrastructure](wiki/infrastructure/index.md) | **seeded** | CI/CD pipelines, secrets in build/deploy, container image builds, rollout/rollback strategy, observability (logs/metrics/alerting) |
| [testing](wiki/testing/index.md) | **seeded** | Writing or structuring automated tests: level choice, cases/assertions, test data, mock decisions, flaky tests (release-process quality → qa) |
| [qa](wiki/qa/index.md) | **seeded** | Release-quality process: release gates, regression scoping, bug reports, severity/priority triage, exploratory testing, automated verification of document deliverables (spec/RFC gates), sourcing a hand-off deliverable that duplicates a generated artifact (writing automated test code → testing) |
| [debugging](wiki/debugging/index.md) | **seeded** | Diagnosing a failure — finding what is wrong and why: reproducing, bisection, hypothesis testing, traces/logs, intermittent failures (fixing the diagnosed fault → its owning domain) |
| [security](wiki/security/index.md) | **seeded** | Trust-boundary decisions: input validation, session-vs-token auth choice, per-resource authorization (IDOR), secrets hygiene, dependency trust, PII handling (XSS rendering → frontend; CI secrets → infrastructure; JWT implementation → backend/frontend auth) |
| [platforms](wiki/platforms/index.md) | **seeded** | OS-level differences breaking code across macOS/Linux/Windows: shell portability, BSD-vs-GNU CLI, filesystem case/line endings, Unicode normalization in text/file-name matching, commands inspected before execution, background services/cron, invoking prompt-capable CLIs non-interactively, toolchain version pinning |
| [mobile](wiki/mobile/index.md) | **seeded** | App-side iOS/Android/cross-platform: process death/state survival, offline-first sync, mobile-network calls, store rollout/hotfix strategy, startup time |

All ten domains are seeded. New categories grow via `skills/wiki-ingest/SKILL.md`.
1 change: 1 addition & 0 deletions log.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -37,3 +37,4 @@ Append-only. Format: `## [YYYY-MM-DD] <ingest|revise|lint|gap|contradiction|drif
## [2026-08-03] ingest | Consolidated review of knowledge PRs #6–#13 (8 fork PRs) into 12 pages. New: backend/common/llm (completion-response-validation, context-window-budget), backend/common/integrations (externally-owned-defaults), backend/common/storage (object-key-persistence), infrastructure/containers/host-cgroup-visibility, infrastructure/observability/missing-container-metrics, platforms/environment/unicode-text-matching, platforms/shells/command-text-inspected-before-execution, platforms/processes/non-interactive-cli-invocation, qa/document-verification (spec-document-gates, editing-a-gated-document), testing/quality (checks-that-cannot-pass, spec-artifact-checks, harness-reverse-controls). All cited URLs are per-PR live-verified; three pages were reconciled from two overlapping PR versions each (see revise/dedup entries below).
## [2026-08-03] revise | Reconciled 3 pages from overlapping PR pairs, taking the more complete/better-sourced body and folding in the other's unique cases: backend/common/llm/completion-response-validation (#12 body — tool_calls/function_call carve-out, streaming, Responses API status==incomplete, "reasoning is scratch, not deliverable" — kept in llm/ per #6/#13 category, folded in #6's DeepSeek-first-party edge + the 8,173-char reasoning_content field incident); backend/common/integrations/externally-owned-defaults (#12 generalized body — any repo-external resource — folded in #6's LiteLLM-alias-removed field incident + gateway-config-vs-live-upstream nuance); platforms/processes/non-interactive-cli-invocation (#12 body — GNU-nohup extension precision, ssh -n stdin-detach vs BatchMode, pre-log DNS/TLS/proxy + curl -v — folded in #11's DEBIAN_FRONTEND, pager/color TTY case, wrapper-CLI case, and the no-request-in-gateway-log field incident).
## [2026-08-03] dedup | Dropped 3 candidate pages as duplicates/superseded during the #6–#13 consolidation: testing/docs-as-spec/document-conformance-checks (#9 — same case as testing/quality/spec-artifact-checks from #8: coverage-vs-validity split, per-check negative controls, GFM pipe parsing; #8 kept as canonical, docs-as-spec category not created); backend/common/llm/gateway-model-alias-defaults (#6 — subsumed by the generalized integrations/externally-owned-defaults; the model-alias case is one instance); backend/common/integrations/llm-response-completeness (#12 — folded into llm/completion-response-validation, kept in llm/ for category coherence with context-window-budget).
## [2026-08-04] ingest | qa +1 (NEW category deliverables): generated-artifacts-as-deliverable-source — a hand-off document (ERD/schema/API list) is requested for content the repo already generates from code; re-run the generator and use its output as the body, hand-writing only what it cannot express (scope, narrative, the commit generated from). Split matters: sources say "the best documentation is hand-written" and generators "still require input from humans", so this page does not claim generation replaces writing — it assigns mechanically checkable facts to the generator and judgement to prose. New category `deliverables` because existing qa categories cover gating documents (document-verification), release process, environments, bug reports, and exploratory testing — none covers where a deliverable's content comes from. Field evidence: hand-written schema deliverable matched live DB on 3/19 cross-checked tables, listed 2 non-existent tables, rendered all 14 PKs as `id` against an `<entity>_id` convention; the committed generated ERD matched, and one re-run refreshed 97 → 105 tables. Sources: Write the Docs docs-principles (eliminate content overlap), OpenAPI Best Practices (single description as source of truth), Google docguide (sources next to code).
29 changes: 17 additions & 12 deletions wiki/frontend/state/derived-state.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,12 @@ sources:
- https://react.dev/learn/choosing-the-state-structure
- https://react.dev/reference/react/useMemo
last_verified: 2026-07-10
related: [frontend-state-client-vs-server-state, frontend-rendering-rerender-and-memoization]
related:
[
frontend-state-client-vs-server-state,
frontend-rendering-rerender-and-memoization,
qa-deliverables-generated-artifacts-as-deliverable-source,
]
---

# Values Computable from Existing State or Props
Expand Down Expand Up @@ -40,20 +45,20 @@ you are debugging two copies of the same fact that have drifted apart.

Cases that look derived but need different handling:

| Case | Then |
|------|------|
| Computation is measured-expensive (profiled, perceptible lag) | Still compute — wrap in `useMemo` with the inputs as dependencies; do not move it to state + effect |
| Editable draft initialized from a prop (edit form seeded by an entity) | It is real state: initialize once from the prop (`useState(entity.name)`) and pass a `key={entity.id}` so the component remounts (resetting the draft) when the entity changes |
| Value derived from async/server data (needs a fetch to compute) | It is server state — put it in the server-state cache and transform at read time; see [frontend-state-client-vs-server-state] |
| Derived value must persist across the inputs disappearing (last non-empty result) | It is its own state; set it at the event that produces it, not in an effect watching the inputs |
| Case | Then |
| --------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Computation is measured-expensive (profiled, perceptible lag) | Still compute — wrap in `useMemo` with the inputs as dependencies; do not move it to state + effect |
| Editable draft initialized from a prop (edit form seeded by an entity) | It is real state: initialize once from the prop (`useState(entity.name)`) and pass a `key={entity.id}` so the component remounts (resetting the draft) when the entity changes |
| Value derived from async/server data (needs a fetch to compute) | It is server state — put it in the server-state cache and transform at read time; see [frontend-state-client-vs-server-state] |
| Derived value must persist across the inputs disappearing (last non-empty result) | It is its own state; set it at the event that produces it, not in an effect watching the inputs |

## Instead of

| If you are about to | Do this instead | Why |
|---------------------|-----------------|-----|
| Write a `useEffect` that sets state from other state/props | Compute the value in render | The effect version renders a stale frame first, then re-renders; it is an extra copy that can drift |
| Store `filteredItems` next to `items` + `filter` | Derive `filteredItems` in render | Any update path that touches `items` but forgets `filteredItems` ships a drift bug |
| Store the full selected object in state | Store `selectedId`, derive the object with `find` | The copy goes stale when the source list changes |
| If you are about to | Do this instead | Why |
| ---------------------------------------------------------- | ------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
| Write a `useEffect` that sets state from other state/props | Compute the value in render | The effect version renders a stale frame first, then re-renders; it is an extra copy that can drift |
| Store `filteredItems` next to `items` + `filter` | Derive `filteredItems` in render | Any update path that touches `items` but forgets `filteredItems` ships a drift bug |
| Store the full selected object in state | Store `selectedId`, derive the object with `find` | The copy goes stale when the source list changes |

## Sources

Expand Down
Loading
Loading