V2 · Chapter {chapter.number}
{chapter.title}
{chapter.summary}
diff --git a/AGENTS.md b/AGENTS.md index 8c2f91b..2a59283 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -27,6 +27,13 @@ Do not merge or publish this transition without direct owner authorization. Docu The current v2 proposal inserts Chapter 05, *Engineering Data: From Measurements to Decisions*, and shifts later v2 briefs to 06–13. Keep the existing original twelve published lessons and their canonical calculations unchanged. The shared at-a-glance summary uses data from site/src/data/chapter-glances.ts; do not confuse these summaries with evidence of feature completion. The new v2 reader-preview route is separate from original lesson 05. Synthetic power and mounting fields are teaching assumptions, never physically verified measurements. +## Chapter 1 reader pilot — owner-authorized 15 November 2026 + +The owner approved applying the revised site direction and terminology to Chapter 1 as a local pilot before other chapters. Read project/SITE-DIRECTION.md as the current editorial direction. Implement the complete preview at learn/v2/01-new-engineering-paradigm/ with its own dark reading layout; preserve the original Chapter 1 route, fragments and V0 lab. This authorization supersedes the earlier Home/Learn-only scope for this single pilot. + +The pilot uses a concrete opening, explanatory graphics and optional interactions without the universal six-tile summary. Other chapter layouts stay unchanged pending review. Register complete reader previews separately in site/src/data/chapters.ts and label their status in Home/Learn. Keep conceptual situations distinct from model executions or recorded agent runs. + +After checking in the reviewed work, the owner explicitly requested publication on 15 November 2026. That authorization covers the revised front page, Learn navigation and the v2 Chapter 1 reader preview in this branch. Keep the reader-preview label because editorial review continues. It does not authorize migration of other chapters, publication of the separate v3 manuscripts or changes to the engineering engine. ## V3 approved editorial manuscripts — agents must read first diff --git a/SITE_SPEC.md b/SITE_SPEC.md index 0f7d83b..8397891 100644 --- a/SITE_SPEC.md +++ b/SITE_SPEC.md @@ -2,6 +2,8 @@ **Status:** Proposed baseline · **Version:** 0.1 · **Date:** 2026-10-16 +**Historical release specification.** For the current editorial direction and the authorized Chapter 1 reader pilot, use [project/SITE-DIRECTION.md](project/SITE-DIRECTION.md). The original curriculum and visual direction below document the first release; the V0 technical contracts remain in force. + ## 1. Purpose Executable Engineering Lab is a standalone, practical learning site showing how engineering intent can become structured, connected, executable, and verifiable engineering knowledge. It builds conceptually on [Document-as-Code Lab](https://and-gu.github.io/document-as-code-lab/) without assuming readers completed it. diff --git a/chapters/01-the-new-engineering-paradigm.md b/chapters/01-the-new-engineering-paradigm.md index 8d26c27..116e60c 100644 --- a/chapters/01-the-new-engineering-paradigm.md +++ b/chapters/01-the-new-engineering-paradigm.md @@ -1,15 +1,26 @@ # Chapter 01 — The New Engineering Paradigm -Status: v2 implementation brief (proposed) +Status: owner-authorized reader pilot, 15 November 2026; local preview before wider adoption or publication Part: I — Engineering in the Age of AI ## The one question -Why does faster AI execution require a different engineering environment? +How do software-driven workflows and AI agents change the way we develop systems? ## What the reader must gain -Explain how digital threads and agents reinforce each other; identify the production-versus-review bottleneck; recognize discipline-specific cadences. +Distinguish systems engineering, executable engineering, software-driven workflows, AI assistance and agentic work. Explain how the product system and engineering environment develop together; distinguish AI used in engineering from AI in products; recognize discipline-specific feedback and release cadences. + +## Terminology introduced here +Use the shared definitions and introduction sequence in [the curriculum map](../project/CURRICULUM-MAP.md#terminology-and-introduction-sequence). + +- Establish systems engineering as the scope across software, electronics, physical design, people and use. +- Introduce executable engineering and software-driven workflows through a model, experiment or repeatable check in the opening situation. +- Explain an AI agent as carrying out a defined task with tools, inspecting results and adapting the next step. Introduce agentic engineering as this way of working within the broader category of AI-assisted engineering. +- Distinguish AI used to develop the product from AI contributing to the product's behavior. Neither product AI nor all automation is necessarily agentic. +- Reserve large language model (LLM) detail for Chapter 07 unless a specific example requires it earlier; spell out the term on first use. + +Introduce “We build the machine that builds the machine” through the product system and the engineering environment. Make the people, methods, models, tools and workflows in the second system explicit. ## Opening engineering situation -An operations team proposes a distributed monitoring capability. Compare a document/tool-silo workflow with connected information and bounded agent assistance. +An operations team wants to detect developing equipment faults. The intended use, sensor mounting, signal interpretation and operator response are still open questions. Explain how product questions shape the engineering environment through a clearly conceptual monitoring example. ## Narrative arc 1. Start with a concrete decision or unexpected constraint, not a definition. @@ -20,7 +31,13 @@ An operations team proposes a distributed monitoring capability. Compare a docum 6. Connect the decision to the next engineering question. ## Primary learning experience -Side-by-side interactive lifecycle maps with visible handoff delays and review points; no fabricated productivity numbers. +A two-lane visual connects the product system to the engineering environment through questions and findings. Expand three illustrative findings—mounting behavior, a classifier's missed condition and changed firmware sampling—to inspect the next product work and the next improvement to the engineering environment. A separate comparison distinguishes AI in engineering from AI in products; a cadence schematic shows different feedback loops without invented durations. A reasoning check asks what passing software checks establish about physical mounting. + +## Reader layout and route + +The complete pilot is at `/learn/v2/01-new-engineering-paradigm/`, with a dark sans-serif reading layout, grouped course navigation, compact chapter information and contextual deeper links. Preserve `/learn/01-engineering-intent/` and all original fragments. Chapter 2's bridge points to the planned learning map until a complete reader exists. Home and Learn link to the pilot as a preview. + +The pilot deliberately omits the six-tile At a Glance panel under the updated [site direction](../project/SITE-DIRECTION.md). Other chapter content and layouts await review. ## Reuse and migration from v1 Existing homepage framing and Ch 1 intent explanation; retain Ch 1 V0 lab as legacy/related resource. diff --git a/chapters/07-directing-ai-engineering-agents.md b/chapters/07-directing-ai-engineering-agents.md index 06b8f74..02c27b1 100644 --- a/chapters/07-directing-ai-engineering-agents.md +++ b/chapters/07-directing-ai-engineering-agents.md @@ -8,6 +8,9 @@ What can an agent do on our behalf, and how do we know what actually happened? ## What the reader must gain Set task objective, sources, permissions, tool boundaries, stop conditions and review deliverable; distinguish agent narration from trace and evidence. +## Terminology developed here +Build on the [Chapter 01 vocabulary](../project/CURRICULUM-MAP.md#terminology-and-introduction-sequence). Explain large language model (LLM) at first use, separating the underlying model from the agent's tools, context and execution loop. Contrast interactive AI assistance, predefined automation and an agent selecting and adapting steps toward a delegated objective. Use “agentic engineering” for this working practice; do not use it as a synonym for all AI in engineering or AI in products. + ## Opening engineering situation Agent investigates a bounded DMS proposal, reads approved sources, modifies an isolated fixture, runs checks and opens a reviewable diff. diff --git a/docs/design/chapter-style-guide.fragment.html b/docs/design/chapter-style-guide.fragment.html new file mode 100644 index 0000000..0aa5766 --- /dev/null +++ b/docs/design/chapter-style-guide.fragment.html @@ -0,0 +1,242 @@ + +
Part I · Why and what next
01 The New Engineering Paradigm
02 Planning Under Uncertainty
PART I / CHAPTER 01
+How do we turn faster modeling, agentic work and frequent releases into useful progress across the whole system?
+ +An operations team wants to detect developing equipment faults. The sensor, its mounting and the operator’s response are still open questions. Each experiment develops our understanding of the product—and the means of investigating it.
+Behavior · interfaces · use
People · models · tools
A product question shapes an experiment. Its findings guide both the design and the next engineering capability.
+FOUNDATIONS
Develop the system.
MODEL / RUN / COMPARE
| Role | Desktop | Narrow screen |
|---|---|---|
| Chapter title · 600 weight | 48 px | 34–38 px |
| Section / subsection | 30 / 21 px | 26 / 20 px |
| Opening paragraph | 20 px | 18 px |
| Body · 400 weight | 18 px / 1.7 line height | 16–17 px / 1.7 |
| Diagram labels / captions | 14 / 13–14 px | Keep readable; reflow |
| Short mono labels | 12 px | 12 px |
#0D1011#151A1C#F1F3EF#D7DEDF#B9C2C5#384144#9ED8CB · TEAL#F1D67B · GOLDGRAPHIC LANGUAGE
The signal changes with the mounting.
Check whether the signal remains useful in the intended installation.
Reuse the analysis workflow for the next comparison.
Feedback → a loop.
Alternatives → a comparison.
Dependencies → named links.
Different cadences → separate lanes.
Stack and redraw on mobile. Keep labels at reading size. Explain the consequence in a caption. Pair color with names; use status text for results.
Teal and gold identify the two systems. They do not mean PASS and FAIL. Decorative rules may be subtle; meaningful connectors must remain clearly visible.
+REUSABLE READING PATTERNS
A heading names the idea or action. The paragraph explains why it matters before introducing the mechanism.
Executable engineering puts models, analyses and checks into workflows that can be run, evaluated and improved.
The example is conceptual. A physical conclusion would require suitable measurements, a known configuration and a model whose assumptions apply.
Only what those checks evaluate. Identify the model or physical experiment needed for the mounting question.
Inspect the model →
A contextual link says what the reader will find and whether setup is needed.
End with the engineering insight, then a real next destination. Mark a planned chapter clearly.
Use flowing prose as the default. Reserve panels for figures and interactions; reserve disclosures for optional depth. The main argument stays visible.
+Executable Engineering Lab · A practical learning environment
-Digital Engineering connects knowledge across disciplines. AI agents can accelerate exploration and implementation. The challenge is to use both without losing control of engineering decisions, architecture, or evidence.
-Follow a fictional Distributed Monitoring System from uncertain intent toward progressively more informed engineering decisions. The planned curriculum will explore how software, electronics, mechanical design, integration and verification contribute at different speeds.
-Our approach: specify what we know, explore what we don't, verify what we build, and preserve what we learn.
-Explore the learning path → · Open the existing coverage lab
-V2 curriculum in development. The published lessons and working lab below remain the current learning experience.
-{part.message}
V2 direction: {part.chapters.join(' / ')}
New product development · Systems engineering + AI agents
+Software and AI are changing both the systems we develop and the way we develop them. Executable models, AI agents and repeatable workflows let teams explore designs, test assumptions and deliver smaller increments. The engineering challenge is to turn that pace into better systems—across software, electronics and physical design.
+We develop, operate and improve the engineering environment alongside the product.
+Product system
+Software · electronics
Physical design · AI
Understand use
+Model
and experiment
Integrate
and validate
New product ambitions
change the engineering work
Decide what to test
and what to build next.
New engineering capabilities
expand what we can try
Engineering
environment
People · models
Tools · AI agents
Develop methods and models
+Work with
AI agents
Automate
and evaluate
Can an AI-enabled monitoring device recognise faults reliably enough to be useful, within its power and latency limits?
+Model + prototype
+Engineers define relevant fault scenarios. An AI agent prepares and runs a simulation, inspects the results and revises the analysis; engineers check the assumptions.
+Run + compare
+Compare candidate detection models on representative data. Test missed detections, false alarms, latency and power on the target hardware.
+The workflow is part of the engineering result. Retain the model, dataset, configuration and evaluation code so the team can rerun the experiment after the next change.
+01 / Modelling and exploration
+Use code, simulation, data-driven models and physical prototypes to explore behaviour. AI agents can help implement and explore models; engineers choose the abstraction, check predictions and test where the model stops being useful.
+02 / Teams and workflows
+Give teams responsibility for the models, tools and data they rely on. Automate repeatable analysis, testing and release preparation. Make progress visible through demonstrated behaviour, unresolved questions and dependencies, so engineers and leaders can decide what to improve next.
+03 / Release and feedback
+Small software releases keep the feedback loop moving. Automated tests, AI evaluations and operating data help judge quality. Electronics, mechanical changes and physical validation have their own cadences; frequent software delivery must respect those constraints.
+V2 · Chapter {chapter.number}
{chapter.summary}
The original twelve lessons remain available while the new curriculum is developed. They focus on a deliberately limited single-sensor teaching model. The new multidisciplinary demonstrations and recorded agent workflows are planned, not yet implemented.
-Existing lesson {String(index+1).padStart(2,'0')}
{chapter.summary}
Read Chapter {index + 1} →Chapter {chapter.number} · Preview
+ Start with {chapter.title} +Learn · Curriculum transition
-The new thirteen-chapter journey will connect planning, engineering knowledge, prototyping, progressive specifications, AI agents, integration and engineering evidence.
+Explore how executable models, software-driven workflows and AI agents change systems engineering—from an uncertain product idea to useful improvements in operation.
+The opening chapter is a reader preview of the revised content and dark chapter layout.
+ {chapterPreviews.map(chapter =>{chapter.title} →
{chapter.summary}
Planned curriculum. The full sequence below is planned; available v2 articles are linked separately below. Go to the published lessons for working examples.
-{part.message}
The Chapter 1 preview introduces systems engineering, executable engineering, software-driven workflows and AI-assisted engineering. It explains what AI agents do and distinguishes AI used in engineering from AI in products.
+Chapter 7 will develop agentic engineering through delegated tasks, tool use and evaluation, explaining large language models (LLMs) as part of the underlying technology. Later chapters will apply these terms to models, delivery, physical validation and the engineering environment.
+V2 · Chapter {chapter.number}
{chapter.summary}
Part I · Engineering in the Age of AI / Chapter 01
+Software and AI change the systems we can build—and the work of building them. How do we turn that new pace into useful engineering progress?
+This pilot applies the revised site direction. The monitoring example and agent workflow are conceptual, not a simulation or a recorded agent run. The original lessons and working coverage lab remain available.
+Content and layout revised 15 November 2026. Repository and revision history · Original Chapter 1
+An operations team wants to detect developing equipment faults before they interrupt production. A small monitoring device might help. But which faults matter, where can the sensor be mounted, and what would an operator do with its warning? The product is still a set of questions.
+The team can model signal behavior, prototype an enclosure, try an AI classifier and test an early software version. Each activity can move quickly. The harder task is deciding what those results mean for the system—and what to investigate next.
+ +One product question. Two kinds of engineering work.
Conceptual exampleCan we recognize a useful fault signal on the equipment as it is actually installed?
+↓ Product questions shape the experiments↑ Findings guide the design
+This is a systems engineering problem: develop the whole system across disciplines, people and operating conditions. Sensor electronics, mechanical installation, software and the operator's task all affect whether a warning is useful.
+It is also work on the engineering environment. A new mounting concept may require a better model or a different test fixture. Once the team can repeat that experiment, the next comparison becomes easier to make and explain.
+We develop, operate and improve the engineering environment alongside the product.
+ +Illustrative situations · Expand a finding to see its consequences.
+Compare mounting options before committing to the enclosure. Check whether the signal remains useful under the intended installation conditions.
Revise the model's mounting assumptions and adapt the test fixture. Keep the signal-processing workflow so the next experiment can reuse it.
The useful gain: the next design comparison starts from what the team has learned about the physical system.
+Investigate the missed condition and the consequence for the operator. Revisit the classifier, sensing approach or intended range of use.
Add representative cases to a separate evaluation set. Compare future candidates against these cases and the conditions already understood.
The useful gain: an observed weakness becomes a repeatable evaluation for subsequent candidates.
+Evaluate the changed behavior against the current electronics and sensing assumptions before releasing the increment.
Add a repeatable interface check and retain the tested configuration. Run the check on later changes and schedule physical tests where the change requires them.
The useful gain: frequent software delivery gets earlier feedback about a system dependency.
+A model is more useful to the investigation when the team can change an input, run it and compare the result. A test becomes more useful when it can run again after a change. A workflow becomes more useful when the next person can use it without reconstructing every step.
+We use executable engineering for this approach: models, analyses, tests and parts of the engineering workflow can be run, evaluated and improved. The name describes a way of working; it does not make every engineering judgment executable.
+Software-driven workflows carry this beyond software development. A mechanical engineer can run a parameter study. An electronics engineer can evaluate a signal chain. A test engineer can process measurements and compare configurations. Repeatable execution makes another investigation practical while preserving enough context to interpret it.
+A digital thread maintains the relationships that matter: this model uses that assumption; this experiment tests that configuration; this finding informs that decision. The benefit is that the next investigation can build on the reasoning, rather than rediscovering which result belongs to which design.
+AI-assisted engineering covers AI used in engineering work, from helping an engineer examine an idea to carrying out a delegated task. An AI agent can use tools, inspect their results and adapt its next steps toward a defined objective. We call this way of working agentic engineering. Engineers still frame the task and evaluate the work.
+AI in the engineering environment
+An agent could implement alternative signal-processing models, run them against specified cases, inspect the outputs and revise a candidate. The engineer needs to examine the model, comparison and remaining uncertainty.
+AI in the product
+A classifier could help the monitoring device distinguish a fault signal from normal operation. Its usefulness depends on the data, equipment conditions and consequences of a missed or false warning.
+These are different uses of AI. The classifier need not be an agent or use a large language model (LLM). An LLM is a model technology behind many assistants and agents; it is one part of the surrounding tools and workflow. A fixed script that reruns tests is automation, even if an AI helped write it.
+Useful agent work also changes the team's preparation. Models need usable inputs. Tools need clear interfaces. Results need context. Making those available lets people and agents investigate with the same engineering resources, while keeping the interpretation open to review.
+Faster engineering means shortening the time between a question, an experiment and a useful decision. It also means delivering smaller improvements more frequently when the system can support them. Software releases, model revisions and physical prototypes contribute different kinds of feedback.
+Testing and evaluation belong inside these loops. Verification asks whether specified expectations are met; validation investigates whether the system is suitable for its intended use. Frequent software checks support delivery, while physical behavior and use still need relevant evidence.
+This changes how teams organize and follow the work. Alongside completed tasks, ask which behavior has been demonstrated, which uncertainty remains and which dependency is holding up the next decision. A failed prototype can advance understanding. More generated code does not, by itself, establish product maturity.
+Only what those checks actually evaluate. If they do not represent mounting behavior, they provide no new evidence about it. Use their results to advance the software work, then identify the model or physical experiment needed for the mounting question.
+The engineering takeaway
+The second machine is the people, methods, models, tools and workflows that make engineering possible. Develop it through real product questions. Reuse what already works, add what the next investigation needs, and improve the environment as the team learns.
+The monitoring team now has several possible next steps: understand the mounting, improve the classifier, or test what an operator needs. Which uncertainty deserves attention first—and which work is ready for commitment? That is the question for Chapter 2, Planning Under Uncertainty.
+Executable engineering is this tutorial's working description. The monitoring situations illustrate an approach; they are not measured product results or evidence of a running agent.
+