type

Reference

title

Change authoring workflow

description

Canonical cross-package loop for verified product changes — baseline, unit-focused implementation, area-focused review, documentation, commit, and pre-merge validation.

Change authoring workflow

Single source for how to author and verify a product change in RNFB (bug fix, feature, parity, coverage). Package workflows add artifacts; work queues add ephemeral gate state — neither restates this loop.

Policy: OKF documentation and commit policy. Terms: iteration vocabulary.

Primary loop

flowchart TD
  START([Pick change scope]) --> GA{Need feasibility /<br/>semantics check?}
  GA -->|yes| GAP["gap-analysis<br/>tier: none"]
  GA -->|no| BC{Need before snapshot<br/>or area-focused e2e baseline?}
  GAP --> BC

  BC -->|yes| BASE["baseline-capture<br/>tier: area-focused"]
  BC -->|no| IMPL
  BASE --> IMPL

  IMPL["implementation<br/>tier: unit-focused<br/>Jest + narrow e2e loop"]
  IMPL --> IG{implementation gate<br/>green?}
  IG -->|no| IMPL
  IG -->|yes| REV

  REV["independent-review<br/>tier: area-focused<br/>frozen tree"]
  REV --> RG{review gate<br/>green?}
  RG -->|blocking findings| IMPL
  RG -->|yes| DOC

  DOC{User-facing or<br/>OKF durable updates?}
  DOC -->|yes| DOCS["documentation<br/>tier: none"]
  DOC -->|no| COMMIT
  DOCS --> COMMIT

  COMMIT["commit<br/>tier: none"]
  COMMIT --> PM{Branch ready<br/>to merge?}
  PM -->|yes| FULL["pre-merge-validation<br/>tier: full"]
  PM -->|no| END([Hand off / next item])
  FULL --> END

Work types

Work type	When	Validation tier	Product edits	Commit
`gap-analysis`	Unclear feasibility, export shape, platform support	none	read-only	no
`baseline-capture`	Need before metrics or area-focused e2e on the item	`area-focused`	harness narrow OK locally	no
`implementation`	Author fix/feature + tests	`unit-focused`	yes	no
`independent-review`	Verify frozen diff	`area-focused`	no — frozen tree	no
`documentation`	User docs + durable OKF updates	none	docs only	no
`commit`	Gates closed for the item	none	staging only	yes
`pre-merge-validation`	Branch merge gate	`full`	revert narrowing first	no

Commands per work type: validation checklist — link only; do not duplicate here.

Validation tiers

Tier id strings: iteration vocabulary § validation tier identifiers.

flowchart LR
  subgraph unitFocused ["unit-focused — implementation"]
    F1[Area harness narrowing required]
    F2[Jest + package-scoped tests]
    F3[".only OK locally"]
    F4[Fast e2e subset]
    F5[Never commit narrowing or .only]
  end

  subgraph areaFocused ["area-focused — baseline-capture / independent-review"]
    A1[Area harness narrowing required]
    A2[Full loaded package spec]
    A3[No .only]
    A4[Frozen tree for review]
  end

  subgraph full ["full — pre-merge-validation"]
    P1[Revert all narrowing]
    P2[All modules / full app]
    P3[Once per branch before merge]
  end

E2e scope, pre-flight, and harness gate: running e2e § agent rule (canonical commands only), validation tiers, harness narrowing gate.

Command rule: Agents run only agent command policy allowlisted commands for install, prepare, and validation — no improvised yarn workspace … prepare, yarn jet, or package-scoped build probes.

Gates

Gate	Closes when
`implementation`	`implementation` work type complete — code plus unit-focused-tier checks green; static analysis green on the diff
`review`	`independent-review` complete — area-focused-tier checks green on frozen tree; applicable validation checklist rows green (including static analysis)
`commit`	Durable commit exists for the item

Trust rule: Code on disk or in git with review still open is unverified until independent-review closes the gate.

If review finds blocking issues, return to implementation (unit-focused), then repeat independent-review (area-focused).

Frozen tree

Required for independent-review and for any :test-cover run that closes the review gate:

No edits to packages/**, tests/** (except reverting .only), or bundle-affecting OKF docs during the run.
Wait for or cancel in-flight runs before editing again.

Keep implementation and independent-review in separate passes. E2e enforcement during runs: running e2e § rules.

Host rule

On a shared dev host during change authoring:

One :test-cover at a time — never overlap unit-focused-tier and area-focused-tier runs.
Every run starts from running e2e § pre-flight (host-clear probes, services, harness tier).
Use only canonical e2e commands. Stalled runs → stalled run detection.

`implementation` inner loop

flowchart TD
  P0[Pre-flight: host clear, services, harness tier]
  P1[Edit product code + tests]
  P2[Jest — package or scoped paths]
  P3{Native touched?}
  P3 -->|no| P4[macOS e2e when TS/runtime path]
  P3 -->|yes| P5["native rebuild + platform e2e"]
  P4 --> P6{Green?}
  P5 --> P6
  P6 -->|no| P1
  P6 -->|yes| STATIC[Static analysis — validation checklist § lint]
  STATIC --> DONE([Close implementation gate])
  P0 --> P1

Host rule: one :test-cover at a time; never overlap unit-focused and area-focused tiers on one host (§ host rule).

Static analysis before handoff: Before closing the implementation gate, run the validation checklist § lint and formatting rows (yarn lint:js; yarn lint:markdown / yarn lint:spellcheck when docs changed). Fix violations in product code — do not hand off with lint failures. Command list lives only in the checklist; do not duplicate here.

Step detail: running e2e § unit-focused iteration loop.

Platform SDK bridge contracts (blocking)

Before changing native bridge code that calls a platform SDK (Firebase Android/iOS, OS APIs, vendor SDKs, etc.):

Read each platform's official API signature and docs independently — do not assume Android, iOS, and Web behave the same because the RNFB bridge presents a unified JavaScript surface.
Verify null vs empty string — many SDKs treat absent values (null/nil) and empty strings ("") differently; map bridge fields to the SDK parameter the docs specify for "absent" values.
Do not apply defensive parity — fixing platform A does not justify the same change on platform B without checking B's contract (e.g. @Nullable vs nonnull, optional vs required).
Record evidence — link or cite the reference URL / header signature in the work queue note or triage report when the fix is native-only on one platform.

E2e diagnosis escalation

When unit-focused e2e fails and product cause is unclear:

Confirm pre-flight was complete (prepare completion gate when lib/** changed, host-clear probes, services, area narrowing, RNFBDebug = true).
If the same failure repeats on back-to-back runs with no assertion progress and the host is known clean → sub-suite narrow (running e2e § fail-fast): one spec file or describe.only on the failing band (e.g. aggregate count() / average() / sum() only). Still unit-focused; never commit narrowing.
If sub-suite runs still fail without actionable assertion text → add temporary native instrumentation (NSLog, adb logcat tags, etc.) on the code path under test; use running e2e § diagnosing hangs for log commands. Remove instrumentation before commit and before area-focused gate closure on a frozen tree.
Do not treat Jet WS disconnect / orchestration timeout alone as product failure — stalled run detection and pre-flight recovery first.

This escalation applies to any change authoring item, not only namespace removal. Work queues record outcomes; they do not restate this loop.

`independent-review`

On a frozen tree:

Revert all .only.
Keep area narrowing; run area-focused-tier e2e for loaded package spec(s) on every required platform (serial; pre-flight each run).
Run applicable validation checklist rows — blocking: static analysis § lint and formatting (yarn lint:js on the frozen tree; markdown/spellcheck when docs touched); yarn reference:api when public surface changed. For packages registered in compare:types, yarn compare:types is a blocking review gate: the touched package must have zero undocumented or stale differences before review_gate closes. If the global command fails on unrelated registered packages, record/fix that drift in the work queue; do not treat an unrelated failure as permission to skip the touched package's type-parity check.
If the package workflow requires coverage: coverage design § completion signal.
Outcome closes review gate or returns to implementation.

Keep implementation and independent-review in separate passes (§ frozen tree).

Harness narrowing

Before the first :test-cover at unit-focused or area-focused tier: apply package area narrowing in tests/app.js / tests/globals.js even when the branch commit has full harness. tests/app.js has two platform populate blocks — running e2e § area harness (two platform blocks): edit both if (Platform.other) and if (!Platform.other) (or disable both with Pattern A). Set RNFBDebug = true locally in tests/globals.js (running e2e § fail-fast). Full app load is full tier only.

Kind	`implementation` (unit-focused)	`independent-review` (area-focused)	`pre-merge-validation` (full)	`commit`
Area narrowing	Required before `:test-cover`	Required before `:test-cover`	Revert — all modules	Never
`RNFBDebug = true`	Required locally before `:test-cover`	Required locally before `:test-cover`	Revert — `false`	Never
Single-test (`.only`)	Allowed (diagnosis)	Revert	Revert	Never
Single-suite (`describe.only` / one spec file)	Allowed (diagnosis only — escalation)	Revert	Revert	Never

Package workflows define which module/spec to load (e.g. Firestore → pipeline implementation workflow § narrowing).

Sanity check: pass counts must match loaded scope — not full-app totals (running e2e § gate).

`commit`

One focused commit per item when gates close.
Never stage: area narrowing, any .only, ad-hoc harness edits, or RNFBDebug = true in tests/globals.js (running e2e § before merge, platform coverage gate).
Work queue: before git commit, set the row's commit_subject to the commit's subject line, close commit_gate, and stage the queue doc in the same commit as the product change (documentation policy § work queues). Do not record SHAs in queue docs.

git status
git diff --stat
rg '\.only\(' packages/

Package extensions

Package / area	Adds to this loop
Firestore Pipelines	Compare-types gap pick, serialization matrix, `Pipeline.e2e.js` setup, coverage snapshots — pipeline implementation workflow
Other packages	`okf-bundle/packages/<pkg>/` index when a workflow exists

Ephemeral coordination (gate rows, next_work_type, commit_subject): work queues only — not part of this workflow.

Related docs

Topic	Document
Term ids and queue field schema	iteration-vocabulary.md
E2e commands	running-e2e.md
Validation commands	validation-checklist.md
Coverage policy	coverage-design.md

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Change authoring workflow

Primary loop

Work types

Validation tiers

Gates

Frozen tree

Host rule

`implementation` inner loop

Platform SDK bridge contracts (blocking)

E2e diagnosis escalation

`independent-review`

Harness narrowing

`commit`

Package extensions

Related docs

Uh oh!

FilesExpand file tree

change-authoring-workflow.md

Latest commit

History

change-authoring-workflow.md

File metadata and controls

Change authoring workflow

Primary loop

Work types

Validation tiers

Gates

Frozen tree

Host rule

implementation inner loop

Platform SDK bridge contracts (blocking)

E2e diagnosis escalation

independent-review

Harness narrowing

commit

Package extensions

Related docs

`implementation` inner loop

`independent-review`

`commit`