Add planning baseline: BC, SA, PP and two gateways
Create the Business Case, Stakeholder Analysis (S01 course participant, S02 Udemy coursists, S03 GitHub viewers), Project Plan and the milestone documents MIL-001 (project setup, 6 tasks) and MIL-002 (game implementation, 8 tasks) for the console Blackjack game. Register PP and MIL in the artifact registry, set the PO language to en, and link the synced Gitea milestones in the Gateway Schedule. Refs #1 Refs #2 Refs #3 Refs #4 Refs #5 Refs #6 Refs #7 Refs #8 Refs #9 Refs #10 Refs #11 Refs #12 Refs #13 Refs #14
This commit is contained in:
@@ -0,0 +1,25 @@
|
||||
# Architecture Decision Record (ADR)
|
||||
|
||||
Files: `docs/adr/adr-NNNN-kebab-case-title.md`. `NNNN` is 4-digit and
|
||||
sequential; the ID is `ADR-NNNN` and must match the filename number (an
|
||||
intentional exception to the usual 3-digit IDs). Use
|
||||
`new-artifact.sh ADR --file docs/adr/adr-NNNN-title.md`.
|
||||
|
||||
Cite in `CrossReference` the artifacts this decision is about (pass each
|
||||
with `--cite <ID>=<path>`); ADR has no fixed candidate list.
|
||||
|
||||
## Required sections (after Metadata / Version History)
|
||||
|
||||
- **Context** — the problem, the options evaluated and the forces
|
||||
(cost, risk, constraints).
|
||||
- **Decision** — the outcome in one or two sentences, no hedging.
|
||||
- **Consequences** — two bold labels, **Positive:** and **Negative:**, each
|
||||
with a bullet list.
|
||||
- **Affected Artifacts** — other artifacts impacted, as `[ID]` links, or a
|
||||
single `-` if none.
|
||||
|
||||
Allowed statuses: `Proposed`, `Accepted`, `Rejected`, `Deprecated`,
|
||||
`Superseded by ADR-NNNN`; no others (an ADR is never `Approved`). Status
|
||||
changes (`Proposed` → `Accepted` → `Deprecated` / `Superseded by ADR-NNNN`, or
|
||||
`Proposed` → `Rejected`) are new rows in `## Version History` (only the two
|
||||
latest are kept; earlier ones stay in git); never rewrite a retained row.
|
||||
@@ -0,0 +1,45 @@
|
||||
# Business Case (BC)
|
||||
|
||||
Cite in `CrossReference` only if the instance exists (`new-artifact.sh` checks this for you):
|
||||
|
||||
- **SA** — Stakeholders section — cite S-IDs instead of re-describing roles
|
||||
- **BMC** — Cost–Benefit Assessment must agree with its cost/revenue blocks
|
||||
- **BPMN** — Forward: the process that realizes the objectives
|
||||
- **KPI** — Success Criteria — each criterion is operationalized by a KPI
|
||||
- **UCD** — Forward: scope expressed as actors and goals
|
||||
|
||||
## Required sections (after Metadata / Version History)
|
||||
|
||||
In this order:
|
||||
|
||||
1. **Executive Summary** — one paragraph framing the problem and the
|
||||
proposed solution.
|
||||
2. **Methodological and Standards Foundation** — states the methodology
|
||||
(e.g. Larman's *Applying UML and Patterns*) and quality standards (e.g.
|
||||
ISO/IEC 25002/25010/25019) the rest of the document and downstream
|
||||
artifacts are built on.
|
||||
3. **Problem Statement** — the recurring problems that justify the project.
|
||||
4. **Business Opportunity** — what becomes possible if the problem is
|
||||
solved.
|
||||
5. **Objectives** — concrete, verifiable statements of what the project
|
||||
will achieve.
|
||||
6. **Scope** — split into `## In Scope` and `## Out of Scope` subsections.
|
||||
7. **Expected Benefits** — split into `### Tangible Benefits` and
|
||||
`### Intangible Benefits`.
|
||||
8. **Strategic Alignment** — how the project supports organizational goals.
|
||||
9. **Success Criteria** — a table with explicit, measurable targets (not
|
||||
aspirations).
|
||||
10. **Risks** — a table with `Risk | Impact | Mitigation` columns; every
|
||||
risk must have a mitigation.
|
||||
11. **Assumptions** — bullet list, kept distinct from Constraints.
|
||||
12. **Constraints** — bullet list, kept distinct from Assumptions.
|
||||
13. **Cost–Benefit Assessment** — a table (`Costs | Benefits`); may be
|
||||
qualitative if explicitly justified.
|
||||
14. **Stakeholders** — a table referencing exact stakeholder IDs from the
|
||||
project's Stakeholder Analysis (e.g. `S01`, `S07`) if `SA` exists per
|
||||
the CrossReference check above. **Never re-describe stakeholder roles
|
||||
inline instead of citing their IDs** — this is the single most common
|
||||
defect found when reviewing Business Cases (see `QC-BC-001`'s Common
|
||||
Defects).
|
||||
15. **Recommendation** — a single, unambiguous "proceed" or "do not
|
||||
proceed" statement.
|
||||
@@ -0,0 +1,21 @@
|
||||
# Business Model Canvas (BMC)
|
||||
|
||||
Cite in `CrossReference` only if the instance exists (`new-artifact.sh` checks this for you):
|
||||
|
||||
- **BC** — Objectives the canvas operationalizes; cost/revenue must agree with its Cost–Benefit Assessment
|
||||
- **SA** — Value Propositions, Customer Segments, Channels — cite S-IDs
|
||||
- **BPMN** — Key Activities — cite the process that realizes them
|
||||
- **KPI** — Measures of value proposition / revenue — cite KPI IDs
|
||||
|
||||
## Required sections (after Metadata / Version History)
|
||||
|
||||
1. **Purpose / Scope** — one paragraph.
|
||||
2. **Canvas** — all 9 building blocks populated, none empty: Key Partners,
|
||||
Key Activities, Key Resources, Value Propositions, Customer
|
||||
Relationships, Channels, Customer Segments, Cost Structure, Revenue
|
||||
Streams. Must stay reviewable as a single, concise overview.
|
||||
3. **Assumptions** — explicit and testable (how would we know it is wrong?).
|
||||
4. **Consistency Check** — Revenue Streams vs Cost Structure agree;
|
||||
Segments/Channels match stakeholder groups from `SA`.
|
||||
|
||||
Cite Business Case objectives (`[BC-001]`) instead of restating them.
|
||||
@@ -0,0 +1,22 @@
|
||||
# BPMN Process Model (BPMN)
|
||||
|
||||
Cite in `CrossReference` only if the instance exists (`new-artifact.sh` checks this for you):
|
||||
|
||||
- **BC** — The stated business goal/objective the process serves
|
||||
- **SA** — Participants / lanes — cite S-IDs
|
||||
- **UCD** — Forward link: actors and goals derived from this process
|
||||
|
||||
## Required sections (after Metadata / Version History)
|
||||
|
||||
1. **Purpose and Business Goal** — the Business Case objective realized
|
||||
(cite `[BC-001]`).
|
||||
2. **Participants (Pools / Lanes)** — every participant, mapped to an `SA`
|
||||
stakeholder ID where one exists.
|
||||
3. **Process Diagram** — valid BPMN 2.0. Message flows cross pool
|
||||
boundaries; sequence flows do not. Keep the diagram source next to the
|
||||
document (BPMN has no native markdown form) so it stays diffable.
|
||||
4. **Element Table** — `Element | Type | Lane | Description` for every
|
||||
event, activity and gateway. Every gateway states its type (XOR/AND/OR)
|
||||
and its matching join.
|
||||
5. **Path Coverage** — every path runs from a start event to a defined end
|
||||
event; no dead ends.
|
||||
@@ -0,0 +1,27 @@
|
||||
# Design Class Diagram (DCD) (DCD)
|
||||
|
||||
Cite in `CrossReference` only if the instance exists (`new-artifact.sh` checks this for you):
|
||||
|
||||
- **DM** — Concepts each design class refines — names must stay consistent
|
||||
- **SD** — Messages that become method signatures
|
||||
- **ERD** — Forward: persistence of the classes' attributes
|
||||
|
||||
## Required sections (after Metadata / Version History)
|
||||
|
||||
1. **Purpose and Scope**.
|
||||
2. **Diagram** — PlantUML class diagram: visibility markers (`+` `-` `#`)
|
||||
on every member; association vs aggregation vs composition vs dependency
|
||||
used per true ownership/lifecycle; multiplicity and navigability on every
|
||||
association.
|
||||
3. **Class Table** — `Class | Refines (Domain Model concept) |
|
||||
Responsibility (one sentence) | Attributes | Operations`. SOLID applied;
|
||||
no god classes; names consistent with the Domain Model.
|
||||
4. **Method Traceability** — `Method signature | Operation Contract / SD
|
||||
message`; every method traces to one.
|
||||
5. **Pattern Annotations** — `Pattern | Classes | Rationale`, explicit.
|
||||
6. **Dependency Check** — note confirming no circular class/package
|
||||
dependencies (or an explicit justification).
|
||||
|
||||
## Terminology
|
||||
|
||||
Class and attribute names are the IT terms from the dictionary (`DICT`), not the PO terms the Domain Model uses.
|
||||
@@ -0,0 +1,25 @@
|
||||
# Domain Dictionary (DICT)
|
||||
|
||||
Cite in `CrossReference` only if the instance exists (`new-artifact.sh` checks this for you):
|
||||
|
||||
- **BC** — The business goals the vocabulary serves
|
||||
- **SA** — The Product Owner (and other business stakeholders) whose terms are recorded
|
||||
- **DM** — Concepts whose PO terms are recorded
|
||||
|
||||
## Required sections (after Metadata / Version History)
|
||||
|
||||
1. **Purpose and Scope** — the PO language (from the registry's `Languages`
|
||||
section) and what the dictionary covers.
|
||||
2. **Dictionary** — one row per term:
|
||||
`PO term | Language | IT term | Definition | Used as PO term in | Used as IT term in`.
|
||||
The definition is written in the PO language. "Used as PO term in" and
|
||||
"Used as IT term in" list artifact types (for example `DM` and `OC, SD,
|
||||
DCD, ERD`).
|
||||
3. **Rules** — the register split (PO term in the Domain Model, use cases and
|
||||
user stories; IT term in the Operation Contract, Sequence Diagram, Design
|
||||
Class Diagram and ERD) and one IT term per PO term.
|
||||
|
||||
Keep the dictionary in step with the Domain Model: a new concept gets a row
|
||||
in the same change. When the PO language is English, the PO and IT columns can
|
||||
still differ (a business word against a technical one); keep the file anyway
|
||||
when the two registers use different words.
|
||||
@@ -0,0 +1,26 @@
|
||||
# Domain Model (DM)
|
||||
|
||||
Cite in `CrossReference` only if the instance exists (`new-artifact.sh` checks this for you):
|
||||
|
||||
- **UC** — Source of every concept (noun phrases) — cite each `UC-*` used
|
||||
- **UCD** — Scope check: actors/goals the model must cover
|
||||
- **SSD** — Forward: system operations that act on these concepts
|
||||
|
||||
## Required sections (after Metadata / Version History)
|
||||
|
||||
1. **Purpose and Scope** — which use cases the model covers.
|
||||
2. **Diagram** — PlantUML class diagram (or linked source) showing
|
||||
**concepts, attributes and associations only — no operations**.
|
||||
Business language throughout ("Sale", not "SaleTable"/"SaleClass").
|
||||
3. **Concept Table** — `Concept | Definition | Attributes | Source (use
|
||||
case noun phrase / glossary)`. Every concept traces to a noun in a use
|
||||
case or glossary. Attributes are simple domain data, not foreign-key-like
|
||||
references (model those as associations).
|
||||
4. **Association Table** — `From | Association name (with reading
|
||||
direction) | To | Multiplicity (both ends)`. All multiplicities present.
|
||||
5. **Generalizations** — only true "is-a" relationships, never inheritance
|
||||
for code reuse.
|
||||
|
||||
## Terminology
|
||||
|
||||
Concept names are the PO terms recorded in the dictionary (`DICT`); add a row there for each new concept.
|
||||
@@ -0,0 +1,22 @@
|
||||
# Entity Relationship Diagram (ERD) (ERD)
|
||||
|
||||
Cite in `CrossReference` only if the instance exists (`new-artifact.sh` checks this for you):
|
||||
|
||||
- **DCD** — **Required source**: classes/attributes each entity persists; data types must match
|
||||
|
||||
## Required sections (after Metadata / Version History)
|
||||
|
||||
1. **Purpose and Scope**.
|
||||
2. **Diagram** — PlantUML entity diagram with PK/FK marked on every entity and
|
||||
cardinality (1:1, 1:N) on every relationship; N:M relationships resolved
|
||||
through explicit junction entities.
|
||||
3. **Entity Table** — per entity: `Attribute | Type | PK/FK | Nullable |
|
||||
Source (DCD class.attribute)`. Types consistent with the DCD; consistent
|
||||
naming, no implementation-specific abbreviations.
|
||||
4. **Relationship Table** — `Entity | Cardinality | Entity | FK | Rule`.
|
||||
5. **Normalization Notes** — 3NF confirmed; any denormalization documented
|
||||
with its performance justification.
|
||||
|
||||
## Terminology
|
||||
|
||||
Entity and column names follow the IT terms from the dictionary (`DICT`), not the PO terms the Domain Model uses.
|
||||
@@ -0,0 +1,16 @@
|
||||
# Governance / ARB Workflow (GOV)
|
||||
|
||||
One per project: `docs/sqa/governance.md`. Sections: Purpose, ARB Review
|
||||
Workflow (submission → QC review → `RC-*` record → Go/No-Go → sign-off →
|
||||
Traceability update), RACI by Artifact Category, Escalation Rules, Cadence.
|
||||
The template has the standard text; fill the RACI.
|
||||
|
||||
**RACI cells use exact stakeholder IDs from the project's Stakeholder
|
||||
Analysis (`S<NN>`), never role names.**
|
||||
|
||||
Related singletons (edit the existing file, no scaffold needed):
|
||||
- `PRC` — `framework/process/review-checklist-process.md`, the narrative
|
||||
review procedure. Framework-level; do not add project data.
|
||||
- `CSG` — `docs/sqa/coding-standards-governance.md`. Scope is *defining and
|
||||
governing* (not enforcing) language standards and style guides, as set by
|
||||
the project Business Case's scope.
|
||||
@@ -0,0 +1,20 @@
|
||||
# KPI Definitions (KPI)
|
||||
|
||||
Cite in `CrossReference` only if the instance exists (`new-artifact.sh` checks this for you):
|
||||
|
||||
- **BC** — The Success Criteria row each KPI is aligned to (`[BC-001]`)
|
||||
|
||||
## Required sections (after Metadata / Version History)
|
||||
|
||||
1. **Purpose** — which Business Case success criteria this document
|
||||
operationalizes.
|
||||
2. **KPI Definitions** — one row per KPI: `KPI ID | Name | SMART statement |
|
||||
Baseline | Target | Business Case Success Criterion | Owner | Frequency &
|
||||
Method | Data Source`.
|
||||
3. **Thresholds** — per KPI: acceptable / at-risk / failing bounds.
|
||||
4. **Reporting** — where results are reported and to whom.
|
||||
|
||||
Rules: every KPI is SMART (reject goals/activities like "improve quality");
|
||||
baseline *and* target are both present; `Owner` is a stakeholder ID from
|
||||
the project's Stakeholder Analysis (e.g. `S07`), never free text; give KPIs stable IDs (`KPI-01`, …) so
|
||||
Milestones can cite them.
|
||||
@@ -0,0 +1,48 @@
|
||||
# Milestone / Gateway (MIL)
|
||||
|
||||
Cite in `CrossReference` only if the instance exists (`new-artifact.sh` checks this for you):
|
||||
|
||||
- **BC** — The objective / constraint (e.g. project duration) the milestone traces to
|
||||
- **KPI** — The KPI IDs evaluated at this gate
|
||||
- **US** — Forward: the user stories (`US-<v>.<NN>`) that deliver this gateway
|
||||
|
||||
## Required sections (after Metadata / Version History)
|
||||
|
||||
1. **Purpose** — what decision this gate supports.
|
||||
2. **Deliverable** — the concrete, tangible output evaluated (never just a date).
|
||||
3. **Go / No-Go Criteria** — objectively checkable, one per row.
|
||||
4. **Dependencies** — other milestones that must precede this one.
|
||||
5. **Traceability** — the Business Case objective and/or KPI ID(s) it maps to.
|
||||
6. **Ownership** — owner and approving reviewer as `SA` stakeholder IDs.
|
||||
7. **Target Date** — consistent with Business Case constraints.
|
||||
8. **Tasks** — the implementation-level breakdown for this phase, one row
|
||||
per task: `# | Task | Summary | Needs its own Use Case/User Story? |
|
||||
Reference`. `Task` is a short title (becomes the Issue title on sync);
|
||||
`Summary` is one to three sentences of real context — what the task
|
||||
actually involves and why, grounded in this project's own documents, not
|
||||
a restatement of the title — so someone reading the Issue on Gitea/GitHub
|
||||
understands it without opening this file (becomes the Issue body).
|
||||
|
||||
## Breaking a phase into tasks
|
||||
|
||||
Not every task needs a use case — only model one when the task is something
|
||||
a user, or another system, actually does:
|
||||
|
||||
- **Needs a use case/user story** — "User resets password", "Admin exports
|
||||
customer report", "Payment service processes refund". Set the column to
|
||||
`Yes` and put the `US-…`/`UC-…` ID in Reference.
|
||||
- **Plain task, no use case** — "Refactor authentication middleware", "Add
|
||||
database index", "Upgrade React version", "Fix null-pointer bug", "Add
|
||||
unit tests", "Configure CI pipeline", "Optimize SQL query". Set the column
|
||||
to `No` and leave Reference blank, or point at the design artifact it
|
||||
implements (`DCD-…`, `OC-…`).
|
||||
|
||||
The hierarchy is: Business goal → Feature/requirement → Use case/user story
|
||||
→ Tasks. The use case explains *why* a feature exists; tasks explain *how*
|
||||
the team implements it — most tasks stay at that level.
|
||||
|
||||
## Syncing to Gitea/GitHub
|
||||
|
||||
Each `MIL-*` gateway becomes one Milestone on the git host; its `## Tasks`
|
||||
row become Issues assigned to that milestone. Use the `project-planning`
|
||||
skill and `framework/scripts/sync-project.sh` — do not create these by hand.
|
||||
@@ -0,0 +1,27 @@
|
||||
# Operation Contract (OC)
|
||||
|
||||
Cite in `CrossReference` only if the instance exists (`new-artifact.sh` checks this for you):
|
||||
|
||||
- **SSD** — **Required source**: each contract traces to exactly one SSD message
|
||||
- **DM** — Classes/associations named in pre/postconditions
|
||||
- **SD** — Forward: the design realizing each contract's postconditions
|
||||
|
||||
## Required sections (after Metadata / Version History)
|
||||
|
||||
One block per system operation, each containing:
|
||||
|
||||
1. **Operation** — complete signature: name, parameter types, return type
|
||||
(must match the SSD message).
|
||||
2. **Cross References** — the SSD message it traces to (one contract per
|
||||
message) and the Domain Model concepts touched.
|
||||
3. **Preconditions** — required state before execution, expressed in Domain
|
||||
Model terms.
|
||||
4. **Postconditions** — state changes only, in Larman's style: *instance
|
||||
created / instance associated / attribute modified*. Declarative ("what"),
|
||||
never algorithmic ("how"); avoid vague text like "system processes the
|
||||
request".
|
||||
5. **Exceptions** — error conditions, each with the failing precondition.
|
||||
|
||||
## Terminology
|
||||
|
||||
Use the IT terms from the dictionary (`DICT`), not the PO terms the Domain Model uses.
|
||||
@@ -0,0 +1,64 @@
|
||||
# Project Plan (PP)
|
||||
|
||||
One per project: `docs/project-plan.md`. Schedules the phases (`MIL-*`
|
||||
gateways) over the Business Case's timeline/duration constraint.
|
||||
|
||||
Cite in `CrossReference` only if the instance exists (`new-artifact.sh`
|
||||
checks this for you):
|
||||
|
||||
- **BC** — the duration/constraint and objectives the plan schedules against
|
||||
- **SA** — the communication cadence (e.g. sync frequency) the phase length follows
|
||||
- **MIL** — every phase gateway the plan schedules (add each as it is created)
|
||||
- **US** — the gateway user stories, once they exist
|
||||
|
||||
## Required sections (after Metadata / Version History)
|
||||
|
||||
1. **Purpose** — what the plan schedules and over what constraint.
|
||||
2. **Planning Assumptions** — start date, phase length, any resolved
|
||||
conflicts the phasing follows (cite `SA`/`BC` where relevant).
|
||||
3. **Gateway Schedule** — one row per phase: `Gateway | Document | Window |
|
||||
Decision date | Owner | Stories | Main deliverable | Milestone`. One row
|
||||
per `MIL-*`. `Milestone` links to that phase's Gitea/GitHub Milestone once
|
||||
`sync-project.sh` has created it (see "Phases, tasks and the git host"
|
||||
below); leave it blank until then.
|
||||
4. **Timeline diagram** — a PlantUML Gantt chart, one bar per phase plus a
|
||||
milestone marker per Go/No-Go decision.
|
||||
5. **Scope Coverage** — maps each Business Case scope item to the gateway
|
||||
that delivers it.
|
||||
6. **Dependencies** — the gateway order (usually a simple chain) and what a
|
||||
No-Go does to later dates.
|
||||
7. **Plan Risks** — risks specific to the plan (schedule slip, dependency
|
||||
risk), separate from the Business Case's own Risks table.
|
||||
8. **Open Issues** — anything unresolved (start date to confirm, ambiguous
|
||||
targets, missing checklists needed by a later phase).
|
||||
|
||||
## Phases, tasks and the git host
|
||||
|
||||
Each phase is a `MIL-*` gateway document (see `references/MIL.md`), which
|
||||
also holds that phase's task breakdown in its own `## Tasks` section. The
|
||||
Project Plan does not repeat the tasks — it only lists the phases and their
|
||||
schedule, plus a link to each phase's Milestone once synced (see above). Use
|
||||
the `project-planning` skill to break a phase into tasks and sync phases (as
|
||||
Milestones) and tasks (as Issues) to Gitea/GitHub:
|
||||
|
||||
```bash
|
||||
bash framework/scripts/sync-project.sh # dry run — prints the plan, no network calls
|
||||
bash framework/scripts/sync-project.sh --apply # creates/updates Milestones and Issues
|
||||
```
|
||||
|
||||
`--apply` needs a token: `GITEA_TOKEN` (Gitea, a personal access token — not
|
||||
a deploy key) or `gh auth login` (GitHub). `GITEA_TOKEN` can come from a
|
||||
`.env` file at the project root (copy `.env.example`, never commit it). If
|
||||
`.env` is missing or has no token when a sync is needed, ask the user for
|
||||
one and create `.env` from `.env.example` with it rather than skipping the
|
||||
sync or inventing a value.
|
||||
|
||||
After a real `--apply` run, copy each Milestone's URL into the Gateway
|
||||
Schedule's `Milestone` column (a content update, not a status change — it
|
||||
does not need a new `## Version History` row).
|
||||
|
||||
## Validating
|
||||
|
||||
`PP` has no QC checklist yet (open item) — validate a plan against the
|
||||
Business Case constraint it schedules and against `## Go / No-Go Criteria`
|
||||
in each `MIL-*` it lists, rather than a dedicated checklist.
|
||||
@@ -0,0 +1,44 @@
|
||||
# Quality Criteria checklist (QC)
|
||||
|
||||
A QC checklist is the reusable review checklist for one artifact **type**.
|
||||
It lives in the framework (`framework/qc/qc-<type>.md`), is
|
||||
project-independent, and **must never name or link a real artifact
|
||||
instance** (no `[BC-001]`, no `RC-*`, no stakeholder IDs). Refer to types
|
||||
generically ("the Stakeholder Analysis").
|
||||
|
||||
- **ID:** `QC-<short-name>-<version>` (e.g. `QC-BC-001`); the version starts
|
||||
at `001` and only changes when the checklist itself is revised.
|
||||
- **Create:** `new-artifact.sh QC --id QC-XX-001 --file framework/qc/qc-<type>.md
|
||||
--cite QC-<adjacent>=framework/qc/qc-<adjacent>.md ...`
|
||||
- **CrossReference:** the QC checklists immediately backward and forward in
|
||||
Larman's chain, in both directions:
|
||||
|
||||
```
|
||||
QC-SA → QC-BC → { QC-BMC, QC-BPMN, QC-KPI } → QC-MIL
|
||||
QC-BC, QC-SA → QC-UCD → { QC-US, QC-UC }
|
||||
QC-UC → QC-DM → QC-SSD → QC-OC → QC-SD → QC-DCD → QC-ERD
|
||||
QC-ADR ↔ QC-DCD, QC-ERD
|
||||
QC-DCD, QC-ADR → { QC-PY, QC-CL, QC-CPP, QC-CS } (language code checklists)
|
||||
```
|
||||
|
||||
## Version History statuses
|
||||
|
||||
The statuses are `Proposed`, `Accepted`, `Rejected` and `Deprecated`, as for every
|
||||
artifact type (rule in the `artifact` skill, "Version History rule").
|
||||
|
||||
## Required sections (after Metadata / Version History)
|
||||
|
||||
- **Purpose** — why this type matters, what decision it supports.
|
||||
- **Quality Criteria Checklist** — `# | Criterion | Level | ISO/IEC 25010
|
||||
Characteristic(s) | Notes`. `Level` is `Mandatory` (baseline every instance
|
||||
must meet) or `Optional` (advanced, may be deferred); a checklist with an
|
||||
extra column (e.g. `Format`) keeps `Level` right after `Criterion`. Every criterion is tagged with at least one of
|
||||
the eight ISO/IEC 25010:2023 characteristics (Functional Suitability,
|
||||
Performance Efficiency, Compatibility, Usability, Reliability, Security,
|
||||
Maintainability, Portability). Never add an untagged criterion.
|
||||
- **Common Defects** — anti-patterns a reviewer rejects on sight.
|
||||
- **Traceability Rule** — Backward / Forward bullets with the same `[QC-*]`
|
||||
labels as `CrossReference`.
|
||||
|
||||
Also add an entry to `framework/CHANGELOG.md`. Reviews of real instances are
|
||||
recorded in the project as `RC-*` records, not in the checklist.
|
||||
@@ -0,0 +1,34 @@
|
||||
# SQA Review Record (RC)
|
||||
|
||||
One record per review of a specific artifact instance against its QC
|
||||
checklist. Create one for **every** artifact instance in the project.
|
||||
|
||||
- **File:** `docs/sqa/reviews/rc-<NNN>-<instance-slug>.md`
|
||||
- **ID:** `RC-NNN`, sequential across all artifact types (the registry's
|
||||
Next Available Version for `RC`).
|
||||
- **Create:** `new-artifact.sh RC --file docs/sqa/reviews/rc-NNN-<slug>.md
|
||||
--cite <INSTANCE-ID>=<instance path> --cite QC-<SHORT>-001=framework/qc/<checklist>.md`
|
||||
|
||||
## Required sections (after Metadata / Version History)
|
||||
|
||||
- **Artifact Under Review** — links to the instance and to the QC checklist
|
||||
used.
|
||||
- **Checklist Results** — `# | Criterion | Status (Pass/Fail/N-A) |
|
||||
Evidence/Notes`, one row per criterion copied from the QC checklist, in
|
||||
the same order.
|
||||
- **Overall Verdict** — Go / Go-with-conditions / No-Go, with rationale.
|
||||
- **Action Items** — `Action | Owner | Due`. `Owner` is a stakeholder ID from
|
||||
the project's Stakeholder Analysis, never a role name. Every `Fail` and
|
||||
every condition gets an item.
|
||||
|
||||
## After the review
|
||||
|
||||
- The reviewer must not be the artifact's author (see governance).
|
||||
- Add or update the instance's row in the Traceability Matrix, including
|
||||
this `RC-*` in "Last Reviewed".
|
||||
- On **Go**, set the reviewed artifact's latest `## Version History` row to
|
||||
`Accepted` and the row before it to `Deprecated` (`Approved` is not a
|
||||
status). On Go-with-conditions the status stays `Proposed` until the action
|
||||
items are closed. If the change is refused for good, set the row to
|
||||
`Rejected` (the earlier `Accepted` row stays).
|
||||
- Step-by-step narrative: `framework/process/review-checklist-process.md`.
|
||||
@@ -0,0 +1,27 @@
|
||||
# Stakeholder Analysis (SA)
|
||||
|
||||
Cite in `CrossReference` only if the instance exists (`new-artifact.sh` checks this for you):
|
||||
|
||||
- **BC** — Business Case objectives each stakeholder concern traces to (Business Goal Alignment section)
|
||||
|
||||
## Required sections (after Metadata / Version History)
|
||||
|
||||
1. **Purpose** — why the analysis exists and the methodology it follows.
|
||||
2. **Stakeholder Summary Table** — `ID | Name | Role/Title | Organization |
|
||||
Power Level | Interest Level | Quadrant | Primary Concern (Business
|
||||
Language)`. Every row fully filled; no unclassified stakeholder.
|
||||
3. **Power/Interest Classification Rationale** — narrative per quadrant,
|
||||
consistent with the table.
|
||||
4. **Primary Concerns and FURPS+ Mapping** — each concern in business
|
||||
language *and* mapped to a FURPS+ attribute.
|
||||
5. **Communication Requirements** — channel, frequency, deliverable type,
|
||||
tied to a project phase or milestone.
|
||||
6. **Conflicting Interests and Mitigations** — every conflict has a
|
||||
mitigation.
|
||||
7. **Traceability Analysis** — stakeholder → actor/use case mapping, and
|
||||
business-goal alignment citing Business Case (`[BC-001]`) objectives.
|
||||
8. **Sign-Off**.
|
||||
|
||||
Stakeholder IDs (`S01`, `S02`, …) are **stable: never renumbered or reused**.
|
||||
Every other artifact cites them for RACI, ownership and review assignment
|
||||
(`AGENTS.md` rule 3). Add new stakeholders with the next free `S<NN>`.
|
||||
@@ -0,0 +1,26 @@
|
||||
# Sequence Diagram (Design) (SD)
|
||||
|
||||
Cite in `CrossReference` only if the instance exists (`new-artifact.sh` checks this for you):
|
||||
|
||||
- **OC** — **Required source**: the contract whose postconditions each diagram realizes
|
||||
- **DCD** — Forward: classes/methods these messages become
|
||||
|
||||
## Required sections (after Metadata / Version History)
|
||||
|
||||
One block per realized Operation Contract:
|
||||
|
||||
1. **Realizes** — the contract (`[OC-…]`) and its operation name.
|
||||
2. **Diagram** — PlantUML sequence diagram: sync (solid filled arrow),
|
||||
async (open arrow), returns (dashed); activations matching the call
|
||||
nesting; `create` / `destroy` shown for transient objects;
|
||||
`loop` / `alt` / `opt` fragments for conditional/repeated behavior.
|
||||
3. **Pattern Annotations** — table `Pattern (GRASP/GoF) | Applied to |
|
||||
Rationale`. Patterns are labelled, never implicit.
|
||||
4. **Postcondition Coverage** — `Postcondition | Satisfied by message`;
|
||||
every postcondition of the contract must be covered.
|
||||
5. **Responsibility Check** — a short note showing no god-object receives
|
||||
all messages (low coupling, high cohesion).
|
||||
|
||||
## Terminology
|
||||
|
||||
Use the IT terms from the dictionary (`DICT`), not the PO terms the Domain Model uses.
|
||||
@@ -0,0 +1,21 @@
|
||||
# System Sequence Diagram (SSD) (SSD)
|
||||
|
||||
Cite in `CrossReference` only if the instance exists (`new-artifact.sh` checks this for you):
|
||||
|
||||
- **UC** — **Required source** of every SSD: cite the use case (name and ID) it depicts
|
||||
- **DM** — Concepts behind message parameters / returned values
|
||||
- **OC** — Forward: contract per system operation shown
|
||||
|
||||
## Required sections (after Metadata / Version History)
|
||||
|
||||
1. **Source Use Case** — name and ID (`[UC-…]`) and the specific scenario.
|
||||
2. **Diagram** — PlantUML sequence diagram with just the actor and
|
||||
`:System`; **no internal objects**. Dashed return arrows for operations
|
||||
that produce a result. One scenario per diagram — separate diagrams for
|
||||
alternate/exception flows (or state them out of scope).
|
||||
3. **System Operations Table** — `Step | Message (verb phrase) | Parameters
|
||||
| Return | Use case step`. Messages match the use case's main success
|
||||
scenario step-for-step; justify any deviation. Message names become the
|
||||
Operation Contract names.
|
||||
4. **Lifecycle Notes** — creation/destruction of the System instance where
|
||||
relevant (session/transaction scope).
|
||||
@@ -0,0 +1,15 @@
|
||||
# Traceability Matrix (TM)
|
||||
|
||||
One matrix per project: `docs/sqa/traceability-matrix.md`. It makes the
|
||||
Business Case's cross-artifact traceability target measurable.
|
||||
|
||||
## Required sections (after Metadata / Version History)
|
||||
|
||||
- **Purpose**.
|
||||
- **Traceability Table** — one row per artifact instance:
|
||||
`Artifact Instance | Type | Upstream (Backward Link) | Downstream (Forward
|
||||
Link) | Last Reviewed (RC-ID)`. Add or update a row whenever an instance
|
||||
is created or reviewed.
|
||||
- **Coverage Notes** — which types have no instance yet, and how to read
|
||||
`-`: in Upstream it means foundational; in Downstream it means nothing
|
||||
is built on it yet; in Last Reviewed it means no `RC-*` exists yet.
|
||||
@@ -0,0 +1,18 @@
|
||||
# Reviewer Training (TRN)
|
||||
|
||||
The reusable training material for reviewers. It mitigates the "resistance to
|
||||
standardized reviews" risk of the Business Case. Framework-level, like `PRC`:
|
||||
no project data, no stakeholder IDs, no links to project artifacts. The
|
||||
*record* that a session happened (date, attendees, result) is a project
|
||||
document, written after the session.
|
||||
|
||||
- **File:** `framework/process/reviewer-training.md` (singleton, version `001`).
|
||||
- **Create:** `new-artifact.sh TRN`.
|
||||
- **CrossReference:** `PRC` (the procedure the training teaches).
|
||||
|
||||
## Required sections (after Metadata / Version History)
|
||||
|
||||
Purpose, Audience and Prerequisites, Learning Objectives, Agenda (modules with
|
||||
minutes), Module Notes, Exercises (each with input and expected result),
|
||||
Assessment (how and pass criteria), Session Record (what to capture).
|
||||
Exercises use a seeded, generic example, not a real project artifact.
|
||||
@@ -0,0 +1,21 @@
|
||||
# Reviewer Training Record (TRR)
|
||||
|
||||
The project's record that a reviewer training session happened: the evidence
|
||||
that mitigates the "resistance to standardized reviews" risk and satisfies a
|
||||
"training delivered and recorded" gateway criterion. It records one session
|
||||
of the framework's training material (`TRN`); it holds project data
|
||||
(stakeholder IDs, dates), so it lives in the project, not in the framework.
|
||||
|
||||
- **File:** `docs/sqa/reviewer-training-record.md` (one per project; add a new
|
||||
row under `## Attendees and Assessment` and a Version History row for each
|
||||
further session).
|
||||
- **Create:** `new-artifact.sh TRR --file docs/sqa/reviewer-training-record.md
|
||||
--cite TRN-001=framework/process/reviewer-training.md`.
|
||||
- **CrossReference:** `TRN` (the material that was taught).
|
||||
|
||||
## Required sections (after Metadata / Version History)
|
||||
|
||||
Session (material, date, facilitator, format), Attendees and Assessment
|
||||
(stakeholder IDs, attended, Pass or Not yet against the assessment in the
|
||||
material), Feedback, Follow-ups (action, owner as a stakeholder ID, due).
|
||||
Fill the record after the session; never before.
|
||||
@@ -0,0 +1,35 @@
|
||||
# Use Case (UC)
|
||||
|
||||
Cite in `CrossReference` only if the instance exists (`new-artifact.sh` checks this for you):
|
||||
|
||||
- **UCD** — Actor and use-case names must match it exactly
|
||||
- **US** — Stories this use case decomposes into
|
||||
- **SA** — Stakeholders & Interests — cite S-IDs
|
||||
- **DM** — Forward: concepts derived from this use case's nouns
|
||||
- **SSD** — Forward: the SSD depicting this use case's main scenario
|
||||
|
||||
## Location
|
||||
|
||||
`docs/uc-NNN/uc.md`, one folder per use case (create with
|
||||
`new-artifact.sh UC --file docs/uc-NNN/uc.md`). The artifacts this use case
|
||||
affects are saved in the same folder; see the `project-planning` skill, "Use
|
||||
cases get their own folder".
|
||||
|
||||
## Required sections (after Metadata / Version History)
|
||||
|
||||
Pick the format explicitly (`Format: Brief | Casual | Fully Dressed`) and
|
||||
state the **scope/level** (summary, user-goal, subfunction). Always: primary
|
||||
actor, pre/postconditions, goal-perspective wording with no UI or
|
||||
implementation detail.
|
||||
|
||||
- **Brief** — a single paragraph summarizing only the main success scenario.
|
||||
- **Casual** — informal multi-paragraph narrative; may mention some
|
||||
alternate flows.
|
||||
- **Fully Dressed** — all sections, in order: Scope, Level, Primary Actor,
|
||||
Stakeholders and Interests (cite `SA` S-IDs), Preconditions,
|
||||
Postconditions (success guarantee), Main Success Scenario (numbered
|
||||
steps), Extensions / Alternative Flows (reference `<<include>>` /
|
||||
`<<extend>>` use cases), Special Requirements / Business Rules (per step),
|
||||
Open Issues.
|
||||
|
||||
Title and actor names must match `UCD` and `US` exactly.
|
||||
@@ -0,0 +1,24 @@
|
||||
# Use Case Diagram (UCD)
|
||||
|
||||
Cite in `CrossReference` only if the instance exists (`new-artifact.sh` checks this for you):
|
||||
|
||||
- **SA** — Each actor traces to a stakeholder need — cite S-IDs
|
||||
- **BC** — Scope / objectives the boundary reflects
|
||||
- **US** — Forward: stories whose role must match an actor here
|
||||
- **UC** — Forward: the use cases detailing each goal shown
|
||||
|
||||
## Required sections (after Metadata / Version History)
|
||||
|
||||
1. **Purpose and Scope** — the system boundary in words.
|
||||
2. **Diagram** — actors with correct stereotypes (`<<Actor>>`,
|
||||
`<<System>>`), a labelled system boundary, `<<include>>` / `<<extend>>`
|
||||
used per UML 2.5.1 (not as generic "uses"). Embed PlantUML or link the
|
||||
diagram source; no UI or implementation detail.
|
||||
3. **Actor Table** — `Actor | Stereotype | Stakeholder ID (SA) | Goals
|
||||
(use cases)`. No orphan actors: every actor appears in at least one use
|
||||
case.
|
||||
4. **Use Case Table** — `Use Case | Actor(s) | Goal`, names as **verb
|
||||
phrases describing actor goals** ("Place Order"), not system operations
|
||||
("Validate Input").
|
||||
5. **Relationships** — every `<<include>>` / `<<extend>>` with a one-line
|
||||
justification.
|
||||
@@ -0,0 +1,22 @@
|
||||
# User Story (US)
|
||||
|
||||
Cite in `CrossReference` only if the instance exists (`new-artifact.sh` checks this for you):
|
||||
|
||||
- **UCD** — The story's role must match an actor defined here
|
||||
- **UC** — The use case each story traces to
|
||||
- **BC** — Objective / epic the story ultimately supports
|
||||
- **MIL** — The gateway (epic) each story delivers — one or more stories per gateway
|
||||
|
||||
## Required sections (after Metadata / Version History)
|
||||
|
||||
1. **Purpose and Scope** — the epic(s) covered.
|
||||
2. **Story List** — each story with a stable ID `US-<doc-version>.<NN>` (e.g.
|
||||
`US-001.01`, so it cannot be confused with the document ID `US-001`):
|
||||
- Statement: **As a** `<actor>`, **I want** `<goal>`, **so that**
|
||||
`<benefit>` — one goal per story, no implementation detail.
|
||||
- **Acceptance Criteria** — clear and testable (Given/When/Then works).
|
||||
- **Traces to** — the use case (`UC-…`) or epic it comes from; a gateway
|
||||
(`MIL-…`) is an epic.
|
||||
- **Size** — fits a single iteration.
|
||||
3. **INVEST Check** — one line confirming Independent, Negotiable,
|
||||
Valuable, Estimable, Small, Testable (flag any exception with reason).
|
||||
Reference in New Issue
Block a user