LCN Wafer Inspection

Appearance

07. Extending the System Safely ​

Why This Page Exists ​

A good training course should not stop at “understand the code.” It should also teach:

  • how to change the code without breaking the repo’s design

This project already has a strong docs-first workflow. The real playbook is visible in the repo and has been used through the first four slices.

This page explains that workflow from a newcomer’s point of view.

The Core Artifact Flow ​

The implementation flow is documented in Implementation Workflow.

The short version is:

  1. start from Requirements
  2. add or update an ADR if a cross-cutting design decision is involved
  3. write a spec for the slice
  4. write a task with exact scope and verification
  5. implement and test the slice
  6. close out the slice in docs when it is complete

This is one of the best habits in the repo. It creates durable project memory instead of leaving every future engineer or AI tool to reconstruct intent from code alone.

Quick Artifact Flow ​

text
Requirements
    |
    v
 ADR (if cross-cutting decision is needed)
    |
    v
 Spec
    |
    v
 Task / Task Pack
    |
    v
 Code Changes
    |
    v
 Tests + Build Verification
    |
    v
 Close-Out Docs

This is the shortest useful mental model for how the repo expects change to happen.

How Requirements, ADRs, Specs, Tasks, and Tests Fit Together ​

Requirements ​

Requirements define stable product and engineering expectations.

Use them for:

  • vocabulary
  • scope boundaries
  • system-level rules
  • non-functional expectations

Best starting point for newcomers:

ADRs ​

ADRs record choices that have cross-cutting architectural impact.

Examples in this repo:

  • central app state
  • file-backed run history before database persistence
  • JSON recipe catalog before an in-app editor
  • one merged operational maturity slice

Use an ADR when the decision changes more than one file or feature slice.

Specs ​

Specs translate requirements into one bounded feature slice.

A good spec defines:

  • in-scope behavior
  • out-of-scope behavior
  • runtime expectations
  • acceptance criteria

Tasks ​

Tasks turn the spec into an implementation handoff.

The task pack approach is especially important for AI-assisted work because it keeps prompts medium-sized and testable.

Tests ​

Tests are not just post-implementation validation here. They are part of how the repo preserves intended behavior:

  • command guard semantics
  • workflow transitions
  • alarm lifecycle
  • persistence rules
  • streaming and backpressure behavior
  • regression coverage for previously fixed bugs

How To Add One Bounded Feature Slice ​

Use this sequence:

  1. read the relevant requirement sections
  2. decide whether the change needs an ADR
  3. write one slice spec
  4. write one umbrella task
  5. split implementation into medium-sized task prompts if AI tools will be used
  6. implement one bounded concern at a time
  7. run tests and build verification
  8. update docs and close-out notes when done

The key is to keep the slice bounded. A good slice changes one coherent behavior area, not three unrelated subsystems.

Which Docs To Read Before Editing ​

Before Editing Runtime Logic ​

Read:

Before Editing UI Or View Models ​

Read:

Before Editing Infrastructure ​

Read:

Mistakes To Avoid When Using AI Coding Tools ​

1. Handing The Entire Repo To One Prompt ​

This repo works better with medium-sized tasks. Large prompts tend to produce:

  • scope drift
  • shallow reasoning
  • inconsistent state semantics

2. Letting The Tool Invent Runtime Rules ​

The vocabulary and behavior contracts already exist in:

  • requirements
  • ADRs
  • specs
  • tests

The AI should implement from those sources, not improvise them.

3. Changing UI Behavior Without Checking Canonical State ​

A common mistake is to “just make the button work” in the UI layer. In this repo, command semantics belong in the application layer and guards.

4. Adding Hidden State ​

If a change introduces a second truth source outside AppState, the repo becomes harder to reason about.

5. Skipping Verification ​

The task packs in this repo consistently expect:

  • focused tests
  • build verification
  • docs updates when stable behavior changes

Skipping that is usually where AI-generated work becomes expensive later.

A Good Newcomer Workflow ​

If you want to contribute safely:

  1. reproduce the current behavior in the app
  2. read the related scenario page
  3. read the related architecture or course page
  4. find the relevant spec and task
  5. inspect the matching tests
  6. only then begin editing

This repo rewards engineers who build context before changing behavior.

Learning Paths By Role ​

Operator-Minded Learner ​

Focus on:

  • scenarios
  • run history
  • diagnostics
  • fault and recovery flows

Then read this page to understand how those behaviors should be extended safely.

.NET or WPF Developer ​

Focus on:

  • architecture walkthrough
  • runtime module
  • design patterns and .NET techniques
  • then this extension playbook

Architecture-Focused Learner ​

Focus on:

  • requirements
  • ADRs
  • architecture pack
  • implementation workflow
  • then this page

Where To Go After This ​

If you want to keep learning:

Diagram Brief ​

  • Title: Docs-first extension workflow
  • Purpose: Show how a newcomer should move from requirements to ADR to spec to task to implementation to tests and close-out
  • Audience: newcomer contributor using manual coding or AI-assisted coding
  • Nodes: Requirements, ADR, Spec, Task, Task Pack, Code Changes, Tests, Build Verification, Close-Out Review
  • Edges: each artifact feeds the next; tests and verification confirm the implementation; close-out updates stable project memory
  • Grouping: Planning artifacts, implementation artifacts, verification artifacts
  • Caption: Safe extension in this repo depends on respecting the docs-first flow, not skipping straight to code
  • Destination file path: docs/diagrams/source/course-07-extending-the-system.drawio

Docs-first project memory for AI-assisted implementation.

LCN Wafer Inspection Prototype