Skip to content

runbook.md

Latest commit

 

History

History
149 lines (95 loc) · 5.43 KB

runbook.md

File metadata and controls

149 lines (95 loc) · 5.43 KB
Raw

Runbook

Standard Run Sequence

Every commons-idea run follows this order. Steps 1–4 apply to both paths. Steps 5 onward branch by classification.

1. Classify the Idea

Before any spec questions, determine which path applies:

  • Path A — Specialist Contribution: the user is describing expertise in a domain or profession
  • Path B — Product Idea: the user is describing something to build or have made

See intake_classification.md for classification questions and signals.

Record the classification and its basis in processor_notes.md before proceeding.

2. Capture Intent

Ask guided questions to draw out the full picture. Nothing gets skipped or merged. The user does not need to know the structure — the processor discovers it through conversation.

Specialist path questions cover:

  • What field, profession, or trade is this?
  • What does this specialist do — what tasks, decisions, and outputs does it own?
  • What does it explicitly refuse or escalate?
  • What does a correct output look like?
  • What knowledge or training is required?
  • What adjacent specialists does it work alongside?
  • What authoritative sources back this domain?

Product path questions cover:

  • What problem does this solve and who has it?
  • What does the product do — what are the core features?
  • How does a user interact with it?
  • What data does it work with?
  • What are the risks or constraints?
  • What's in scope for the first version, what's deferred?

Preserve everything the user says, including things that fall outside the first version's scope. Deferred items belong in the spec bundle, not discarded.

3. Confirm Understanding

Before generating anything, play back what was captured. Show the user a structured summary of everything that was understood. Ask explicitly:

Is this right? Correct anything that's off before we continue. Nothing generates until you confirm.

No generation happens until the user confirms. If the user corrects something, update the capture and replay the relevant section before proceeding.

4. Record the Input Authority

  • Identify everything that was used as input for the run.
  • Record excluded sources explicitly.
  • Record the run basis in processor_notes.md.

Path A — Specialist Contribution

5A. Generate the Specialist Bundle

Fill the specialist_summary.md template from the confirmed capture. Every section must be complete before the bundle is considered ready.

6A. Validate the Bundle

Apply the Specialist Path Acceptance Gate from validation_rules.md.

7A. Package and Record

  • Place the completed specialist_summary.md in the run output.
  • Suggest submission to labor-commons as a pull request.
  • If a product dimension was also captured, suggest a follow-up product run.
  • Record processor notes and validation results.

Path B — Product Idea

5B. Choose Delivery Mode

Determine the simplest local-first delivery mode that preserves a one-click experience.

See local_delivery_policy.md for mode selection rules.

Reject designs that make the end user solve infrastructure problems. Record the mode choice and reason in processor_notes.md.

6B. Refresh Dynamic Knowledge

Gather current best-practice knowledge only where the specs leave technical choices open. Prefer primary sources. Record source, retrieval date, and reason for use in processor_notes.md. Repeat for each external source used.

7B. Generate the Bundle

Build the spec bundle (structured markdown files) and the user-facing deliverable package:

  • Open My Idea.html — the user-facing entry point
  • bundle_manifest.json — provenance and validation metadata
  • processor_notes.md — processor record
  • acceptance_checklist.md — delivery validation checklist
  • Any additional product assets required by the delivery mode

8B. Validate the Bundle

Apply the Non-Technical User Acceptance Gate from validation_rules.md.

Verify:

  • The idea is visible locally.
  • The primary controls match working behavior.
  • The primary user path uses non-technical language.
  • No runtime network dependency exists on the default path.

9B. Package and Record

  • Place the spec bundle in the run output.
  • Place the deliverable package in the run output.
  • Suggest submission of the spec bundle to commons-specs.
  • Suggest submission of the deliverable to commons-artifacts.
  • If a specialist dimension was flagged at classification, surface the labor-commons suggestion now.
  • Record processor notes, manifest metadata, and acceptance results.

Mandatory Checks Before Closing Any Run

Confirm:

  • The classification is recorded.
  • The user explicitly confirmed the understanding before generation.
  • The processor notes record what came from the user versus what was inferred.
  • The output bundle contains all required files.
  • For product runs: the idea is visible with one click, locally, without internet.
  • For specialist runs: all required sections of the specialist summary are complete.

Required Distinctions

Keep these separate in every run:

  • what the user said
  • what was inferred from the conversation
  • generated outputs
  • validation results

Generated output never becomes new source truth by default.