Handbook
Forge — artifact and decision model
Purpose: Define how artifacts (inputs/outputs) and decisions attach to Forge’s locked canon—lifecycle model (Forge ↔ SDLC ↔ PDLC bridge, Product development lifecycle (PDLC), Software development lifecycle), meeting…
Companion: Forge — meeting model (operational) specifies meetings (cadence, modes, accountability). This document specifies durable artifacts and decision records and how they connect.
Non-goals: Replace project-specific docs/ layouts, duplicate Software architecture body of knowledge ADR guidance, or introduce a second tracking spine.
Design goals and rules
| Goal | Implication |
|---|---|
| Every core meeting and key decision has clear inputs/outputs and ownership | Map artifacts to meetings in § Artifact matrix; name an owner per artifact type. |
| No bureaucracy | Prefer minimal types; reuse Ember Log + existing templates; consumer must exist before adding a type. |
Rules:
- Every artifact must have a consumer (human process, gate, or downstream doc).
- Every artifact must answer why (reasoning / trigger) and for what (intent / outcome)—same bar as Forge — meeting model (operational) per-meeting Why / For what.
- Keep the set minimal but sufficient.
- Classify artifacts (one primary class each; some rows span two when bridged):
| Class | Meaning |
|---|---|
| Planning | Commits scope, sequence, or horizon before execution. |
| Work execution | Describes or tracks units of delivery work. |
| Evidence | Proves quality, readiness, or compliance for a gate or review. |
| Decision | Records a choice, trade-off, or risk acceptance. |
| Learning / improvement | Captures outcomes of inspect-and-adapt; feeds backlog or directives. |
| Directive | Governs how the team works (rules, norms, process)—not product behavior. |
Authoring specification (design brief)
The following block is the authoring checklist used to maintain this document. When extending Forge’s artifact set, satisfy these items and update § Decisions kept / § Drift / § Open questions.
Sources of truth: ForgeSDLC — concept map and term-collision register, Forge & planning — naming reference, Forge — meeting model (operational), Forge — ceremonies & events (prescriptive), Forge ↔ SDLC ↔ PDLC bridge, Product creation → delivery — industry, Forge, and PMI-style map.
Task checklist:
- Define the minimum artifact set for Forge (see § Recommended artifact set).
- For each artifact, specify: purpose; for what; why; owner; Versona contribution; creation trigger; update trigger; required fields; downstream consumers; linked meetings; linked PDLC/SDLC phases—artifact matrix in § Artifact matrix.
- Recommend canonical names and flag redundant or collision-prone names (§ Canonical names and collision register).
- Provide lightweight Markdown schemas for the highest-value artifacts (§ Markdown schemas).
- Include a critical question structure for formal decision documentation plus a decision schema with at minimum: why; for what; options considered; chosen direction; evidence; risks; owner; review date / revisit trigger.
Evaluated artifact names (minimum): Opportunity/problem; discovery/validation; Product Increment / release-slice planning; Spark definition; Decision Record; Review evidence pack; Assay packet; Release/launch; Retro Record; Directive file; ADR (technical decision).
Recommended artifact set
Minimum durable types teams should be able to point to (paths are typical; projects may namespace under docs/ or forge/ per Forge workspace):
| # | Canonical artifact | Primary class | Canon pointer |
|---|---|---|---|
| 1 | Ore (intake item) | Planning + work execution | ForgeSDLC — concept map and term-collision register, Forge — major processes & flow maps |
| 2 | Ingot (refined, plannable) | Planning + work execution | Same |
| 3 | Forge Spark (delivery unit) | Work execution | Same; Spark definition = Ingot + Spark breakdown at Planning |
| 4 | Charge (daily commitment view) | Work execution | Daily operations |
| 5 | Product Spark plan (PoC/MVP/phase/release plan) | Planning | Product planning, Release plan — {Product Spark name} |
| 6 | Ember Log (operational decision memory) | Decision | Daily operations, ForgeSDLC — concept map and term-collision register Decision Record row |
| 7 | ADR (architecture decision record) | Decision | Software architecture body of knowledge |
| 8 | Directive (team working rules) | Directive | Forge — ceremonies & events (prescriptive) retro → directives |
| 9 | Review evidence pack (increment + evidence posture for Review) | Evidence | Forge — meeting model (operational) § Review |
| 10 | Assay packet (release candidate + checklist + rationale) | Evidence + decision | Assay Gate — {Product Spark name}, Assay Gate |
| 11 | Release / launch record (what shipped, where, flags) | Evidence (+ PDLC P4 handoff) | Release notes + bridge to P4 Launch in PDLC ↔ SDLC bridge |
| 12 | Retro → experiment / directive trace | Learning + directive | Documented retro outputs with owner and evidence per Forge — ceremonies & events (prescriptive) |
| 13 | Opportunity / problem (often as Ore + product docs) | Planning | P1 → Ore; may live in docs/product/ per Product functional documentation blueprint |
| 14 | Discovery / validation (experiments, learnings) | Evidence + learning | PDLC P1–P2; feeds Ore and Product Spark scope |
Not a separate Forge artifact type: a second “decision database” if Ember Log + ADR + directives already cover operational, architectural, and team-rule decisions (ForgeSDLC — concept map and term-collision register).
Artifact matrix
Summary of the evaluated names. “Spark definition” is realized as Ingots + phase-tagged Sparks committed in Planning, not a separate document unless the team adds one.
| Artifact (evaluated name) | Canonical Forge mapping | Purpose (short) | For what | Why | Owner (typical) | Versona contribution | Creation trigger | Update trigger | Required fields (minimum) | Downstream consumers | Linked meetings | PDLC / SDLC |
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Opportunity / problem | Ore + product context | Capture raw problems/ideas | Feed refinement and prioritization | Avoid silent funnel loss | Product hat | Product / strategy lenses | Intake | Re-scope, merge, reject | Problem statement, value hypothesis | Refinement, roadmap | Refinement, ad hoc | P1 |
| Discovery / validation | PDLC experiments + evidence | Learn before scaling commitment | Validate assumptions cheaply | Reduce wrong build | Product + research | Discipline Versonas at P2 | Hypothesis | Learn / kill / pivot | Hypothesis, method, result | Ore backlog, Product Spark scope | Refinement, review | P1–P2 |
| Product Increment / release-slice planning | Product Spark plan | Horizon scope for a slice | Align delivery to a releasable chunk | Make Assay and roadmap coherent | Product / PM | PM Versona, roadmap gates | New slice / milestone | Scope change | Goals, out-of-scope, success measures | Planning, Assay, GTM | Planning | P3 |
| Spark definition | Ingot + Forge Spark list | Executable breakdown | Commit iteration work | Translate plan to tractable units | Owner + Engineering | Decomposition drafts | Planning | Re-plan mid-iteration | IDs, AC, phase tags | Daily sync, review | Planning | P3 |
| Decision Record | Ember Log entry | Operational decision memory | Recover “why” later | Auditability and fewer re-debates | Owner / governance | Prompt to log at §5 / activities | Decision made | Supersede with new log line | See Formal decision (Ember Log block) | Backlog, Assay, retros | Any | P3–P6 |
| Review evidence pack | Review inputs bundle | Show increment + quality posture | Iteration accountability | Early signal before Assay | Whole team | Prep drafts | End of iteration | Each iteration | Demo, test summary, known issues | Assay readiness, Ember Log | Review | P3–P4 |
| Assay packet | Assay Gate evidence + Assay Gate — {Product Spark name} | Release readiness proof | Ship vs not yet | Protect users and commitments | Governance steward | Security/compliance checks | RC + criteria ready | New RC | Checklists, gaps, result | Launch, ops, stakeholders | Assay Gate | P4 |
| Release / launch artifact | Ship record + comms handoff | What went out and how it was activated | Market/ops alignment | Close loop PDLC P4 | Product + engineering | Release notes drafts | Successful Assay | Patch / hotfix | Version, scope, flags, notes | Customers, support, metrics | Assay (prep), launch sync | P4 |
| Retro Record | Retro notes + directive trace | Improve system | Sustainable change | Encode learning | Team; experiment owner | Effectiveness review | Retro | Next retro | Themes, experiments, evidence | Directives, Ore | Retro | P5 |
| Directive file | sdlc/, .cursor/rules/, team norms |
Govern how we work | Consistent execution | Stability without heroics | Named owner + approver | May encode Versona norms | Retro graduation / policy change | Policy review date | Change rationale, evidence | All execution | Retro | P3–P6 |
| ADR / technical decision | docs/adr/ style ADR |
Architecture significance | Long-lived tech coherence | Onboard and avoid rework | Tech lead | Architecture Versona | Significant design fork | Supersede ADR | Context, decision, consequences | Implementation, reviews | Refinement, design | P2–P3 |
Canonical names and collision register
| Use this | Avoid / clarify |
|---|---|
| Ember Log for day-to-day decision memory | “Decision Record” as a fourth bucket—map to Ember Log (ForgeSDLC — concept map and term-collision register). |
| ADR for architecture | “Technical Decision Record” only as plain-language alias for ADR—not for Ember Log or directives. |
| Directive for team rules | Charter / working agreement: merge into directives or link explicitly. |
| Product Spark | Release slice, product increment = aliases; Forge Spark = task-level—never interchange. |
| Assay packet | Align with evidence package language in Forge — meeting model (operational); template: Assay Gate — {Product Spark name}. |
| Review evidence pack | Do not merge with Assay packet—Review judges readiness to pursue Assay; Assay is release verdict. |
| User persona (PDLC) vs Versona (Forge) | Forge & planning — naming reference. |
Critical questions (formal decision)
Use at ad hoc decision meetings and whenever logging a non-trivial choice in the Ember Log:
- What decision is being made (one sentence)?
- For what outcome are we optimizing this week / increment?
- Why now—what breaks if we defer?
- Options considered (including “do nothing”)?
- Evidence we relied on—what would falsify this later?
- Risks and mitigations—who owns each?
- Revisit trigger—date or signal to re-open?
Architecture-only decisions use the ADR template instead; process changes that govern the team belong in directives with retro evidence.
Markdown schemas
1. Formal decision (Ember Log block)
Use inside ember-logs/YYYY-MM-DD.md for decisions that need more than one line:
### Decision — <short title>
- **Why:** <reason / forcing function>
- **For what:** <outcome or constraint this enables>
- **Options considered:** <A | B | C>
- **Chosen direction:** <pick>
- **Evidence:** <links, metrics, session ids>
- **Risks:** <bullet list + owners>
- **Owner:** <name / role>
- **Review date / revisit trigger:** <YYYY-MM-DD or signal>
2. ADR (pointer)
Author full ADRs per Software architecture body of knowledge. Ember Log entries should link to the ADR file rather than duplicating architecture detail.
3. Directive change (retro graduation)
Full templates: Retro Record —