How the v2.1 pre-review pipeline works · 2026-05-15

Before the v2.1 walkthroughs, we ran the remaining five domains through a structured pre-review. This page explains the pipeline so you can re-run it, audit it, or trace any commit back to the research that produced it.
Frame: a kanban board with four columns. Each column is a phase. Work flows left to right. Every artifact has a path. Every decision has an ID.

Why a kanban frame? Toyota's lesson: make the work visible. Five domains × ~200 items is too much to hold in one head. A board with clear columns, standard cards, and a paper trail lets anyone pick up the thread mid-way.

1The four-phase pipeline

Four columns. Each column has a small team, a defined input, a defined output, and a fixed artifact location on disk. The board flows left to right; work does not skip columns.

Phase A Raw Audit

Team — 4 parallel lens auditors

  • Spec-Fidelity lens
  • Workflow Realist lens
  • Data-Model lens
  • Consistency lens

Output

21 raw lens files

~365 raw findings

Location on disk

docs/admin-spec-v2-1/
pre-review/_raw/

Card shape

Severity · Triage · Confidence · Reasoning · Recommendation

Phase B Depth Investigation

Team — 1 Lead + 3 specialists

  • Lead — cross-domain synthesis
  • Data-model specialist
  • Workflow specialist
  • UX-pattern specialist

Input

21 raw files from Phase A

Output

71 chunked investigations

+1 Lead synthesis (_deeper-findings.md)

+5 per-domain punch lists

Location on disk

pre-review/_depth/
pre-review/07-…-11-…md

Phase C Decision Packages

Team — 1 Lead + 5 converters

  • Lead — cross-domain agenda
  • 1 converter per domain (07, 08, 09, 10, 11)

Input

5 punch lists from Phase B

Output

5 stakeholder-ready packages

+1 cross-domain walkthrough agenda

200 items, each with default direction

Location on disk

pre-review/
decision-packages/

Phase D Implementation

Team — 1 Lead + primitives + 4 domain implementers

  • Lead — sequencing & QA
  • Primitives implementer (X8, X9, X10)
  • Domain implementers — 07, 09, 10, 11
  • Domain 08 (Billing) — held

Input

5 decision packages from Phase C

Output

~89 items shipped as mockup code

Branch: v2.1/phase-d

Location on disk

src/pages/v2/*
src/data/*

Findings
Synthesis
Decisions
Shipped

Each column is a single working pass. No column re-opens a previous one. If Phase D finds a missing detail, the decision package is updated by amendment, not edited in place — the chain stays auditable.

2Five domain swim lanes

The same four phases applied to each of the five remaining v2 domains. Billing was explicitly held at Phase D pending a dedicated billing pass — visible in the yellow-striped cell below.

Domain Phase A — Raw audit Phase B — Depth + punch list Phase C — Decision package Phase D — Shipped to mockup
07 Teacher Mgmt/v2/teacher-management 4 lens files~75 findings 4 Blockers · 8 Should-fix · 10 Nice · 15 FYI= 37 items Approved21 DECIDED-PROPOSED · 5 NEEDS-DECISION · 4 DEFER ~29 items shippedincl. T2 Manual Placement Queue (new screen), T6 multi-select chip matrix
08 Billing/v2/billing 4 lens files~85 findings 8 Blockers · 12 Should-fix · 21 Nice · 13 FYI= 54 items Approved28 DECIDED-PROPOSED · 12 NEEDS-DECISION · 5 DEFER · 3+ REJECT HELDImplementation paused pending dedicated billing pass; package remains the ship-plan when unblocked.
09 Reporting/v2/reporting 4 lens files~70 findings 5 Blockers · 17 Should-fix · 6 Nice · 8 FYI= 36 items Approved25 DECIDED-PROPOSED · 5 NEEDS-DECISION · 2 DEFER · 1 REJECT ~23 items shippedincl. 5-card Composition rebuild, sidebar renames; B5 part-held (billing-dependent)
10 Admin System/v2/admin-system 4 lens files~65 findings 0 Blockers · 13 Should-fix · 12 Nice · 11 FYI= 36 items Approved24 DECIDED-PROPOSED · 3 NEEDS-DECISION · 4 DEFER ~16 items shippedincl. routed Issue Detail page, audit-trail cluster (append-only history + reason capture)
11 Communication/v2/communication 4 lens files~70 findings 7 Blockers · 13 Should-fix · 7 Nice · 10 FYI= 37 items Approved14 DECIDED-PROPOSED · 7 NEEDS-DECISION · 5 DEFER · 1 REJECT ~21 items shippedincl. TaPreviewView component, End Checklist Email Queue; B4 part-held (billing-dependent)

The yellow stripe on Billing is the only scope decision that should jump off this table. Everything else flowed end-to-end; Billing waits for a dedicated review pass.

3A single decision card, end to end

To show how the pipeline actually works in practice, here is one item — T6, the Teacher Management Assignment Matrix — traced from raw finding all the way to live mockup code.

1 Raw finding — two lenses flag the same problem Phase A
The Consistency lens and the Workflow Realist lens independently flag the Assignment Matrix. The matrix uses a three-option Select (New / Returning / Both) — but the canonical enrollment vocabulary across the system uses different categories. The labels collide.
Source: _raw/consistency-07-teacher-management.md Source: _raw/workflow-07-teacher-management.md

Two independent lenses converging on the same screen is the signal that this is real, not noise.

2 Depth investigation — trace the schema gap Phase B
A data-model specialist takes the raw flag and writes a focused investigation. They trace which database table holds the matrix routing, how the legacy enum was used, and what migration cost looks like.
Output: _depth/data-07-assignment-criteria-student-type-routing.md Frontmatter cites: raw/consistency-07-…, raw/workflow-07-… Finding: matrix's "Returning" collapses Continuing + Repeat + Year 2 into one bucket. Cost: one-shot UPDATE migration. Cheap.
3 Lead synthesis — cross-domain theme Phase B Lead
The Lead notices this is not isolated. The same vocabulary mismatch shows up in Reporting (Composition cards), Communication (audience segments), and Billing (Family Plans labels). The matrix is one face of a cross-domain theme.
Output: _depth/_deeper-findings.md Theme: X1 — Canonical 4-category enrollment vocabulary Hits: domains 07, 09, 11 (and 08 fallout) Owner: Reporting B2 (Composition rebuild) — propagates to others.
4 Decision package — concrete recommendation, ratified Phase C
The Teacher Management converter writes T6 as a stakeholder-ready item. Status, evidence, the decision itself, the reasoning, and the file paths to touch.
T6 — Matrix studentTypeRouting enum collides with canonical EnrollmentType Status: DECIDED-PROPOSED (Kamran 2026-05-15) Decision: Replace tri-state Select with multi-select chip control on canonical 5-category enum (Continuing / New / Repeat / Year 2 / Returning). Storage: accepted_enrollment_types JSON column on assignment_matrix_rows. UI default: all 5 ticked (equivalent to today's "Both"). Files: src/data/types.ts · src/data/assignment-matrix.ts · src/pages/v2/teacher-management/assignment-criteria.tsx · docs/admin-spec-v2/07-teacher-management.md §4.3

Path: pre-review/decision-packages/07-teacher-management-decisions.md · search the file for T6.

5 Implementation — commit ships Phase D
The Teacher Management implementer pulls T6 from the package list and ships it. The commit message references the decision-package ID directly, so the chain stays walkable from git log backward.
a232c32 feat(v2.1-phase-d): teacher-mgmt/assignment-criteria — T6 multi-select chip src/pages/v2/teacher-management/assignment-criteria.tsx | 188 +++++++++++++-------- 1 file changed, 116 insertions(+), 72 deletions(-)
6 Visible in mockup Live
The change is now part of the Phase D preview build. Stakeholders see the new chip control directly when they visit the page.
Live preview phase-d.quranflow-admin.pages.dev/v2/teacher-criteria

4Common questions

Click any question to expand. These are the questions colleagues will reasonably ask when they look at the branch for the first time.

How do I find which commit shipped a specific decision?

Search git log by the decision-package ID. Every implementation commit references the ID in its message.

  • git log --grep="T6" — Teacher Mgmt item T6
  • git log --grep="B3" — Blocker B3 in whichever domain
  • git log --grep="X8" — cross-domain theme X8 (raw label sweep)

Commit messages follow the shape feat(v2.1-phase-d): <domain>/<screen> — <ID> <short note>.

How do I trace from a commit back to the original research?

Three hops:

  1. Commit message → find the decision-package ID (e.g. T6).
  2. Open pre-review/decision-packages/07-teacher-management-decisions.md and search for T6 — that item cites the depth file (data-07-assignment-criteria-…md).
  3. Open the depth file. Its frontmatter cites the source raw findings in _raw/ — the lens auditors that originally flagged it.

Every link in the chain is a file in the repo. Nothing lives in chat history or memory.

Was the implementation team working from depth research or the decision packages?

Decision packages. The packages are the authoritative consolidation; depth files are research output.

Working from packages avoids re-deriving the synthesis already done in Phase C. The depth files are still available for any item where the implementer needs the underlying reasoning, but the package text is the spec for what to build.

What didn't ship in Phase D, and why?
  • Billing entirely held — stakeholder decision to defer Billing implementation to a dedicated pass. The package is ready when unblocked.
  • Reporting B5 + Communication B4 (parts) — these inherit from Billing schema decisions, so the billing-dependent parts wait too. The independent parts shipped.
  • Spec documents intentionally not updated — spec edits are post-walkthrough work. Phase D updates the mockup so stakeholders can see and react; the spec gets the final word after.
  • Some component consolidation deferred — e.g. merging ConfirmDialog with the new reason-capture dialog. Tracked for v2.2.
How do I know an item is genuinely decided vs awaiting stakeholder input?

Decision packages use four statuses, all explicit:

  • DECIDED-PROPOSED — team's default; ratify in walkthrough.
  • NEEDS-DECISION — discussion required; default direction is still recorded so we can ship without the walkthrough if needed.
  • DEFER — push to backlog with a named trigger ("revisit when X").
  • REJECT — drop with rationale; the underlying need is addressed by a named alternative.

Every item — including DEFER and REJECT — carries a Recommended direction (default if walkthrough skipped). If a walkthrough is cancelled, we have an ordered ship list. No escape hatches.

What happens if a Phase D implementer disagrees with a decision package?

The implementer flags it back to the Phase D Lead with a written note. The Lead decides whether to amend the package (rare — Phase C is meant to be settled) or override for that single item and document the override in the commit message.

In practice this happened only twice during Phase D and both were resolved by clarifying the package text, not by changing the decision.

Can this pipeline be re-run on a future domain?

Yes — it is designed to be re-runnable. The spawn prompts for each phase are stored in pre-review/_spawn-prompts.md and _TEMPLATE-raw.md / _TEMPLATE-synthesis.md. The same four columns apply to any domain that has a spec, a mockup, and at least one round of stakeholder feedback to compare against.

The Billing pass, when it comes, will follow exactly this shape.

How big was the discipline overhead vs the value?

Roughly 200 items across 5 domains were reviewed. ~89 shipped as code in Phase D. ~32 NEEDS-DECISION items are queued for walkthrough. ~20 DEFER items have a named trigger.

The walkthroughs themselves are now ratify-or-override sessions instead of discover sessions — stakeholders see a default direction on every item before the meeting, so meetings can focus on the genuinely contested calls.

5Kanban principles, applied

Which Toyota Production System principles we borrowed

6Where the files live

docs/admin-spec-v2-1/pre-review/
├── README.md                              start here
├── _spawn-prompts.md                      re-runnable prompts for each phase
├── _TEMPLATE-raw.md                       card shape for raw audits
├── _TEMPLATE-synthesis.md                 card shape for punch lists
├── _raw/                                  Phase A · 21 lens outputs
├── _depth/                                Phase B · 71 investigations + Lead synthesis
├── 07-teacher-management.md               Phase B punch lists, one per domain
├── 08-billing-payments.md
├── 09-reporting.md
├── 10-admin-system.md
├── 11-communication.md
└── decision-packages/                     Phase C · 5 packages + cross-domain agenda
    ├── _walkthrough-agenda.md
    ├── 07-teacher-management-decisions.md
    ├── 08-billing-payments-decisions.md
    ├── 09-reporting-decisions.md
    ├── 10-admin-system-decisions.md
    └── 11-communication-decisions.md

src/                                       Phase D · implementation lands here
├── pages/v2/                              domain mockup screens
└── data/                                  mock data + type definitions
Pull request github.com/almaghrib-engineering/QuranFlow-Admin-Mock/pull/2 Phase D preview phase-d.quranflow-admin.pages.dev/v2

Kamran · 2026-05-15 · Pipeline lives on branch v2.1/phase-d. All artifact paths above are real files in the repo.