Build with Kiro: Photolithography Drift Risk Development Workshop

Duration: 2 hours
Audience: Professional backend developers, manufacturing data platform developers, and semiconductor automation engineers
Primary AWS AI service: Kiro
Workshop focus: Advanced Kiro spec-driven development labs for photolithography equipment drift and process-window risk
Standalone outcome: Developers build and review a TypeScript module that classifies and persists photolithography drift-risk records using Kiro-generated specs, tasks, tests, and review prompts.

Summary

This workshop helps professional developers use Kiro for spec-driven photolithography drift-risk persistence. It narrows AI output to persistence-only scope, defines canonical event models, generates TypeScript mappers and handlers, builds Vitest coverage, reviews duplicate-factor and timeline risks, and enforces direct source-field storage. The labs emphasize minimal patches, non-regression, traceability, and system-design reasoning for semiconductor factory engineering teams through practical review workflows.

1. Workshop Goal

This standalone workshop adds deeper hands-on developer labs for using Kiro in semiconductor factory engineering. The scenario focuses on a photolithography exposure tool where focus offset, chuck temperature, dose stability, stage vibration, vacuum level, and reticle alignment can approach process-control boundaries while tool utilization and average yield still look normal.

Developers will use Kiro to create a feature spec, generate code, add tests, review flawed AI output, and extend the implementation with more realistic factory edge cases. All code examples use equipment drift, process-window risk, wafer-lot exposure, automation control slip, and sensor-risk factors.

2. Developer Learning Objectives

By the end of this workshop, developers can:

1. Use Kiro to create a technical spec for a photolithography drift-risk module.
2. Generate a TypeScript mapper and persistence handler from manufacturing event examples.
3. Preserve existing equipment alarm and automation command logic.
4. Add tests for multi-factor risk events, missing optional fields, duplicate factors, and time semantics.
5. Use Kiro to review unsafe implementations and create minimal patches.
6. Explain each design decision through system-design reasoning.

3. Lab Agenda

4. Lab 1 — Expand the Kiro Spec

Developer task

Create a Kiro spec named:

photolithography-drift-risk-persistence

Prompt rule 1

Prompt goal: Ask Kiro for a first version of a photolithography risk feature.

Create a TypeScript feature for photolithography equipment drift risk persistence.

AI generative result: Kiro may propose a broad monitoring system with dashboards, risk calculations, and alerting.

Explanation: The result may be too broad for a developer workshop because it combines persistence, analytics, and operational actions.

Why result is not good: It can introduce generated risk calculations and control actions that should not be part of a persistence-first feature. In factory automation, generated control logic without strong governance can create operational risk.

Prompt rule 2

Why rule 2 can fix previous issue: This narrows Kiro to a persistence-only feature.

Refine the feature to persistence only. Do not create dashboards, alerts, control actions, or derived risk calculations. Store source event fields for later engineering investigation.

AI generative result: Kiro should produce requirements for mapping and storing source fields.

Explanation: The feature becomes small enough for safe implementation and review.

Prompt rule 3

Why rule 3 can fix previous issue: A photolithography risk event has multiple contributing sensor factors.

The event has one drift_risk_event_id and an array named risk_factors. Create one drift summary record and one factor record per risk_factors item. Link factor records to the summary through drift_risk_event_id.

AI generative result: Kiro should design a parent-child model.

Explanation: This supports process-engineering drill-down from the event to individual sensor contributors.

Prompt rule 4

Why rule 4 can fix previous issue: Kiro may convert sensor values or generate metadata unless told not to.

Store direct source values or null. Do not convert sensor values, do not calculate new risk scores, do not generate ids, do not generate timestamps, and do not store the full event payload.

AI generative result: Kiro should use simple mappings and avoid helper conversion functions.

Explanation: Stored records remain traceable to the source stream.

System design decision

1. A Kiro spec creates a reviewable artifact before code is written. This matters because photolithography process windows are narrow and small field changes can have large yield impact. This is a system-design choice because photolithography drift-risk persistence needs narrow contracts that developers can reason about during save-time, test-time, and review-time feedback. The decision keeps the lab focused on observable behavior instead of broad implementation taste, so learners can connect one rule to one operational failure mode without adding unnecessary platform complexity.
2. A persistence-only scope reduces operational risk. It avoids mixing data capture with automated control behavior. For photolithography drift-risk persistence, the architecture should preserve source evidence and existing event behavior before optimizing developer convenience. This point makes the boundary explicit: generated assistance may propose changes, but the system remains accountable to traceability, reproducibility, and production non-regression. The result is easier to audit and safer to evolve.
3. Parent-child records match the investigation workflow: engineers first identify the risky exposure event, then review individual sensor contributors. The final design point turns the lab action into a durable engineering practice for photolithography drift-risk persistence. It explains how the chosen boundary supports team review, future maintenance, and controlled rollout. By keeping the action minimal and measurable, developers can improve the workflow without hiding risk inside large refactors or implicit assumptions.

5. Lab 2 — Define Photolithography Event Model

Developer task

Ask Kiro to generate a canonical event example for the feature.

Prompt sample

Create a full photolithography drift-risk event example for a TypeScript code comment. Include drift_risk_event_id, fab_id, tool_id, wafer_lot_id, recipe_version, exposure_job_id, process_step, process_window_risk_level, drift_velocity, yield_exposure_level, automation_control_slip_probability, event_time, stream_processing_time, and risk_factors with two sensor factors.

Expected event example

{
  "event_type": "PHOTOLITHOGRAPHY_DRIFT_RISK",
  "drift_risk_event_id": "photo_drift_evt_20260626_001",
  "fab_id": "FAB-HK-ADV-01",
  "tool_id": "LITHO-EXPOSE-07",
  "wafer_lot_id": "LOT-AI-780042",
  "recipe_version": "PHOTO-7NM-R42",
  "exposure_job_id": "EXP-JOB-44019",
  "process_step": "PHOTO_EXPOSURE",
  "process_window_risk_level": "HIGH",
  "drift_velocity": "0.034",
  "yield_exposure_level": "ELEVATED",
  "automation_control_slip_probability": "0.72",
  "event_time": "2026-06-26T09:15:30+08:00",
  "stream_processing_time": "2026-06-26T09:15:33+08:00",
  "risk_factors": [
    {
      "factor_id": "photo_factor_focus_001",
      "sensor_name": "focus_offset",
      "sensor_value": "0.018",
      "control_boundary": "0.020",
      "unit": "micrometer",
      "risk_contribution": "HIGH",
      "factor_time": "2026-06-26T09:15:28+08:00"
    },
    {
      "factor_id": "photo_factor_chuck_temp_002",
      "sensor_name": "chuck_temperature",
      "sensor_value": "82.7",
      "control_boundary": "83.0",
      "unit": "celsius",
      "risk_contribution": "MEDIUM",
      "factor_time": "2026-06-26T09:15:29+08:00"
    }
  ]
}

Business logic explanation: This event captures photolithography process-window exposure when tool-level averages may still appear stable.

Code logic explanation: The event has one parent id and multiple factor ids. Time fields represent source event time, stream-processing time, and individual factor time.

Expected result: Kiro uses this exact shape for mapper and tests.

System design decision

1. A concrete event example prevents field invention during code generation. This is a system-design choice because photolithography drift-risk persistence needs narrow contracts that developers can reason about during save-time, test-time, and review-time feedback. The decision keeps the lab focused on observable behavior instead of broad implementation taste, so learners can connect one rule to one operational failure mode without adding unnecessary platform complexity.
2. Separate time fields protect timeline analysis during incident review. For photolithography drift-risk persistence, the architecture should preserve source evidence and existing event behavior before optimizing developer convenience. This point makes the boundary explicit: generated assistance may propose changes, but the system remains accountable to traceability, reproducibility, and production non-regression. The result is easier to audit and safer to evolve.
3. Factor-level records preserve sensor context needed for root-cause analysis. The final design point turns the lab action into a durable engineering practice for photolithography drift-risk persistence. It explains how the chosen boundary supports team review, future maintenance, and controlled rollout. By keeping the action minimal and measurable, developers can improve the workflow without hiding risk inside large refactors or implicit assumptions.

6. Lab 3 — Generate the Mapper

Prompt sample

Create src/photoDriftRiskMapper.ts. Return null unless event_type is PHOTOLITHOGRAPHY_DRIFT_RISK. For eligible events, return one driftSummary object and one factor object for each risk_factors item. Store direct source values or null only.

Expected code

export type PhotoDriftRiskRecordSet = {
    driftSummary: Record<string, string | null>;
    riskFactors: Record<string, string | null>[];
};

export function mapPhotoDriftRiskEvent(message: any): PhotoDriftRiskRecordSet | null {
    if (message?.event_type !== "PHOTOLITHOGRAPHY_DRIFT_RISK") {
        return null;
    }

    const driftSummary = {
        drift_risk_event_id: message.drift_risk_event_id || null,
        fab_id: message.fab_id || null,
        tool_id: message.tool_id || null,
        wafer_lot_id: message.wafer_lot_id || null,
        recipe_version: message.recipe_version || null,
        exposure_job_id: message.exposure_job_id || null,
        process_step: message.process_step || null,
        process_window_risk_level: message.process_window_risk_level || null,
        drift_velocity: message.drift_velocity || null,
        yield_exposure_level: message.yield_exposure_level || null,
        automation_control_slip_probability: message.automation_control_slip_probability || null,
        event_time: message.event_time || null,
        stream_processing_time: message.stream_processing_time || null
    };

    const riskFactors = (message?.risk_factors || []).map((factor: any) => ({
        factor_id: factor.factor_id || null,
        drift_risk_event_id: message.drift_risk_event_id || null,
        sensor_name: factor.sensor_name || null,
        sensor_value: factor.sensor_value || null,
        control_boundary: factor.control_boundary || null,
        unit: factor.unit || null,
        risk_contribution: factor.risk_contribution || null,
        factor_time: factor.factor_time || null
    }));

    return { driftSummary, riskFactors };
}

Business logic explanation: The mapper prepares photolithography risk records for persistence without changing values.

Code logic explanation: It rejects unrelated events, maps a summary object, loops through factors, and returns both record sets.

Expected result: Eligible input returns one summary and multiple factors; unrelated events return null.

System design decision

1. A pure mapper makes generation easy to test without database dependencies. This is a system-design choice because photolithography drift-risk persistence needs narrow contracts that developers can reason about during save-time, test-time, and review-time feedback. The decision keeps the lab focused on observable behavior instead of broad implementation taste, so learners can connect one rule to one operational failure mode without adding unnecessary platform complexity.
2. Exact event matching avoids processing unrelated factory events. For photolithography drift-risk persistence, the architecture should preserve source evidence and existing event behavior before optimizing developer convenience. This point makes the boundary explicit: generated assistance may propose changes, but the system remains accountable to traceability, reproducibility, and production non-regression. The result is easier to audit and safer to evolve.
3. Direct mapping keeps source telemetry comparable with stored records. The final design point turns the lab action into a durable engineering practice for photolithography drift-risk persistence. It explains how the chosen boundary supports team review, future maintenance, and controlled rollout. By keeping the action minimal and measurable, developers can improve the workflow without hiding risk inside large refactors or implicit assumptions.

7. Lab 4 — Generate Persistence Handler

Prompt sample

Create src/photoDriftRiskHandler.ts. Use mapPhotoDriftRiskEvent. If mapper returns records, insert driftSummary and every riskFactor into an in-memory database. If mapper returns null, call existingFactoryLogic. Keep the handler simple.

Expected code

import { mapPhotoDriftRiskEvent } from "./photoDriftRiskMapper.js";
import { runExistingFactoryLogic } from "./existingFactoryLogic.js";

export class InMemoryPhotoRiskDb {
    public driftSummaries: Record<string, string | null>[] = [];
    public riskFactors: Record<string, string | null>[] = [];

    async insertDriftSummary(record: Record<string, string | null>): Promise<void> {
        this.driftSummaries.push(record);
    }

    async insertRiskFactor(record: Record<string, string | null>): Promise<void> {
        this.riskFactors.push(record);
    }
}

export async function handlePhotoDriftRiskMessage(rawMessage: string, db: InMemoryPhotoRiskDb): Promise<string> {
    const message = JSON.parse(rawMessage);
    const records = mapPhotoDriftRiskEvent(message);

    if (records) {
        await db.insertDriftSummary(records.driftSummary);

        for (const factor of records.riskFactors) {
            await db.insertRiskFactor(factor);
        }

        return "photolithography-drift-risk-persisted";
    }

    return runExistingFactoryLogic(message);
}

Business logic explanation: The handler persists photolithography drift-risk records and delegates all unrelated messages to existing factory logic.

Code logic explanation: The mapper determines eligibility. The handler inserts records only when the mapper returns a record set.

Expected result: The handler creates one summary and multiple factors for eligible events.

System design decision

1. Separating mapper and handler keeps business mapping testable and persistence flow simple. This is a system-design choice because photolithography drift-risk persistence needs narrow contracts that developers can reason about during save-time, test-time, and review-time feedback. The decision keeps the lab focused on observable behavior instead of broad implementation taste, so learners can connect one rule to one operational failure mode without adding unnecessary platform complexity.
2. Delegating unrelated events protects existing operational behavior. For photolithography drift-risk persistence, the architecture should preserve source evidence and existing event behavior before optimizing developer convenience. This point makes the boundary explicit: generated assistance may propose changes, but the system remains accountable to traceability, reproducibility, and production non-regression. The result is easier to audit and safer to evolve.
3. The in-memory database keeps the workshop focused on Kiro-assisted development rather than infrastructure. The final design point turns the lab action into a durable engineering practice for photolithography drift-risk persistence. It explains how the chosen boundary supports team review, future maintenance, and controlled rollout. By keeping the action minimal and measurable, developers can improve the workflow without hiding risk inside large refactors or implicit assumptions.

8. Lab 5 — Generate Tests

Prompt sample

Generate Vitest tests for mapPhotoDriftRiskEvent and handlePhotoDriftRiskMessage. Include eligible event with two factors, unrelated equipment alarm, missing risk_factors, and missing optional summary fields.

Expected test code

import { describe, expect, it } from "vitest";
import { mapPhotoDriftRiskEvent } from "../src/photoDriftRiskMapper.js";
import { handlePhotoDriftRiskMessage, InMemoryPhotoRiskDb } from "../src/photoDriftRiskHandler.js";

describe("photolithography drift risk labs", () => {
    it("maps eligible event to one summary and two factors", () => {
        const result = mapPhotoDriftRiskEvent({
            event_type: "PHOTOLITHOGRAPHY_DRIFT_RISK",
            drift_risk_event_id: "photo_drift_evt_20260626_001",
            fab_id: "FAB-HK-ADV-01",
            tool_id: "LITHO-EXPOSE-07",
            wafer_lot_id: "LOT-AI-780042",
            recipe_version: "PHOTO-7NM-R42",
            exposure_job_id: "EXP-JOB-44019",
            process_step: "PHOTO_EXPOSURE",
            process_window_risk_level: "HIGH",
            drift_velocity: "0.034",
            yield_exposure_level: "ELEVATED",
            automation_control_slip_probability: "0.72",
            event_time: "2026-06-26T09:15:30+08:00",
            stream_processing_time: "2026-06-26T09:15:33+08:00",
            risk_factors: [
                {
                    factor_id: "photo_factor_focus_001",
                    sensor_name: "focus_offset",
                    sensor_value: "0.018",
                    control_boundary: "0.020",
                    unit: "micrometer",
                    risk_contribution: "HIGH",
                    factor_time: "2026-06-26T09:15:28+08:00"
                },
                {
                    factor_id: "photo_factor_chuck_temp_002",
                    sensor_name: "chuck_temperature",
                    sensor_value: "82.7",
                    control_boundary: "83.0",
                    unit: "celsius",
                    risk_contribution: "MEDIUM",
                    factor_time: "2026-06-26T09:15:29+08:00"
                }
            ]
        });

        expect(result?.driftSummary.drift_risk_event_id).toBe("photo_drift_evt_20260626_001");
        expect(result?.riskFactors).toHaveLength(2);
        expect(result?.riskFactors[0].drift_risk_event_id).toBe("photo_drift_evt_20260626_001");
    });

    it("persists eligible event through handler", async () => {
        const db = new InMemoryPhotoRiskDb();
        const result = await handlePhotoDriftRiskMessage(JSON.stringify({
            event_type: "PHOTOLITHOGRAPHY_DRIFT_RISK",
            drift_risk_event_id: "photo_evt_handler_001",
            tool_id: "LITHO-EXPOSE-07",
            risk_factors: []
        }), db);

        expect(result).toBe("photolithography-drift-risk-persisted");
        expect(db.driftSummaries).toHaveLength(1);
        expect(db.riskFactors).toHaveLength(0);
    });

    it("returns null for equipment alarm mapper input", () => {
        expect(mapPhotoDriftRiskEvent({ event_type: "EQUIPMENT_ALARM" })).toBeNull();
    });
});

Business logic explanation: The tests validate mapping, persistence, and rejection of unrelated events.

Code logic explanation: Mapper tests inspect returned records; handler tests inspect inserted records.

Expected result: All tests pass.

System design decision

1. Testing both mapper and handler separates field mapping correctness from persistence flow. This is a system-design choice because photolithography drift-risk persistence needs narrow contracts that developers can reason about during save-time, test-time, and review-time feedback. The decision keeps the lab focused on observable behavior instead of broad implementation taste, so learners can connect one rule to one operational failure mode without adding unnecessary platform complexity.
2. Missing-factor behavior ensures an eligible summary still persists when no factor array is present. For photolithography drift-risk persistence, the architecture should preserve source evidence and existing event behavior before optimizing developer convenience. This point makes the boundary explicit: generated assistance may propose changes, but the system remains accountable to traceability, reproducibility, and production non-regression. The result is easier to audit and safer to evolve.
3. Alarm rejection protects non-risk operational event behavior. The final design point turns the lab action into a durable engineering practice for photolithography drift-risk persistence. It explains how the chosen boundary supports team review, future maintenance, and controlled rollout. By keeping the action minimal and measurable, developers can improve the workflow without hiding risk inside large refactors or implicit assumptions.

9. Lab 6 — Duplicate Factor Review

Developer task

Ask Kiro to review this event for duplicate factor ids.

Prompt sample

Review this photolithography risk event for persistence concerns. The event has two risk_factors with the same factor_id. Do not change code automatically. Explain the risk and suggest a test or review rule.

Expected Kiro result

Concern found.
Two risk_factors use the same factor_id, which may conflict with a factor table primary key.
Suggested test: verify duplicate factor_id input is visible during validation or review.
Suggested review rule: source event quality checks should flag duplicate factor_id values before database insertion.
No mapper change is required in this persistence-only lab unless the production database requires conflict handling.

Business logic explanation: Duplicate factor identifiers can hide or overwrite one sensor contributor in a real database.

Code logic explanation: The mapper stores direct values. Duplicate detection may be a validation layer or review rule rather than part of this simple persistence mapper.

Expected result: Developers understand the distinction between persistence mapping and event-quality validation.

System design decision

1. Duplicate id handling should be an explicit design decision, not an accidental mapper side effect. This is a system-design choice because photolithography drift-risk persistence needs narrow contracts that developers can reason about during save-time, test-time, and review-time feedback. The decision keeps the lab focused on observable behavior instead of broad implementation taste, so learners can connect one rule to one operational failure mode without adding unnecessary platform complexity.
2. Persistence-only code should not silently repair source data. For photolithography drift-risk persistence, the architecture should preserve source evidence and existing event behavior before optimizing developer convenience. This point makes the boundary explicit: generated assistance may propose changes, but the system remains accountable to traceability, reproducibility, and production non-regression. The result is easier to audit and safer to evolve.
3. Event-quality validation can be added as a separate feature when required. The final design point turns the lab action into a durable engineering practice for photolithography drift-risk persistence. It explains how the chosen boundary supports team review, future maintenance, and controlled rollout. By keeping the action minimal and measurable, developers can improve the workflow without hiding risk inside large refactors or implicit assumptions.

10. Lab 7 — Timeline Semantics Test

Prompt sample

Add a test that proves event_time, stream_processing_time, and factor_time remain separate fields. Do not collapse them into one timestamp.

Expected test

it("keeps photolithography risk timeline fields separate", () => {
    const result = mapPhotoDriftRiskEvent({
        event_type: "PHOTOLITHOGRAPHY_DRIFT_RISK",
        drift_risk_event_id: "photo_timeline_001",
        event_time: "2026-06-26T09:15:30+08:00",
        stream_processing_time: "2026-06-26T09:15:33+08:00",
        risk_factors: [
            {
                factor_id: "factor_timeline_001",
                factor_time: "2026-06-26T09:15:28+08:00"
            }
        ]
    });

    expect(result?.driftSummary.event_time).toBe("2026-06-26T09:15:30+08:00");
    expect(result?.driftSummary.stream_processing_time).toBe("2026-06-26T09:15:33+08:00");
    expect(result?.riskFactors[0].factor_time).toBe("2026-06-26T09:15:28+08:00");
});

Business logic explanation: Timeline separation matters because sensor observation, event creation, and stream processing are different moments.

Code logic explanation: The mapper stores each time field in its own output field.

Expected result: The test passes without production code changes.

System design decision

1. Incident review requires accurate event ordering. This is a system-design choice because photolithography drift-risk persistence needs narrow contracts that developers can reason about during save-time, test-time, and review-time feedback. The decision keeps the lab focused on observable behavior instead of broad implementation taste, so learners can connect one rule to one operational failure mode without adding unnecessary platform complexity.
2. Collapsing time fields can hide processing delay or sensor lead time. For photolithography drift-risk persistence, the architecture should preserve source evidence and existing event behavior before optimizing developer convenience. This point makes the boundary explicit: generated assistance may propose changes, but the system remains accountable to traceability, reproducibility, and production non-regression. The result is easier to audit and safer to evolve.
3. Tests make timeline semantics executable documentation. The final design point turns the lab action into a durable engineering practice for photolithography drift-risk persistence. It explains how the chosen boundary supports team review, future maintenance, and controlled rollout. By keeping the action minimal and measurable, developers can improve the workflow without hiding risk inside large refactors or implicit assumptions.

11. Lab 8 — Final Kiro Review Prompt

Review the photolithography drift-risk mapper, handler, and tests. Return PASS or FAIL. Check exact event eligibility, direct source-field storage, no generated metadata, no full payload storage, all risk_factors handled, and timeline fields kept separate. Suggest minimal patches only.

Expected Kiro output

PASS
- Exact event eligibility is used.
- Direct source fields are mapped.
- No full payload, generated id, generated timestamp, or derived calculation is present.
- All risk_factors are handled through an array loop.
- Timeline fields remain separate.

12. Completion Checklist

• Kiro spec created.
• Photolithography event example created.
• Mapper generated and tested.
• Handler generated and tested.
• Duplicate factor review completed.
• Timeline semantics test added.
• Final Kiro review completed.

Additional Hands-on Developer Labs for Advanced Developers

These additional labs extend the photolithography drift-risk development workshop without repeating the earlier spec, event model, mapper, handler, tests, duplicate-factor review, timeline lab, or final review checklist. The new advanced focus is spec traceability, idempotent persistence policy, schema evolution, dependency boundaries, and production-readiness review for photolithography risk modules.

13. Lab 9 — Requirements-to-Test Traceability Matrix

Developer task

Ask Kiro to create a traceability matrix that links photolithography persistence requirements to tests and review evidence.

Prompt sample

Create a requirements-to-test traceability matrix for the photolithography drift-risk persistence module. Include exact event eligibility, direct source values, parent-child factor linkage, missing risk_factors behavior, timeline separation, unrelated event delegation, and no generated metadata. Keep it markdown and do not add new requirements.

Expected Kiro result

# Photolithography Drift Risk Traceability Matrix

## Requirement: exact event eligibility
- Evidence: mapper returns records only for PHOTOLITHOGRAPHY_DRIFT_RISK
- Test: maps eligible event to one summary and two factors
- Negative test: returns null for EQUIPMENT_ALARM
- Review check: no includes("RISK") or broad string matching

## Requirement: direct source values or null
- Evidence: summary and factor fields use source fields with null fallback
- Test: missing optional summary fields remain null
- Review check: no Number conversion, normalization helper, generated score, or derived status

## Requirement: parent-child factor linkage
- Evidence: every factor uses parent drift_risk_event_id
- Test: factor drift_risk_event_id equals summary drift_risk_event_id
- Review check: no generated factor parent id

## Requirement: missing risk_factors behavior
- Evidence: eligible event persists one summary and zero factors
- Test: handler persists summary when risk_factors is absent or empty
- Review check: array fallback is present

## Requirement: timeline separation
- Evidence: event_time, stream_processing_time, and factor_time remain distinct
- Test: keeps photolithography risk timeline fields separate
- Review check: no single created_at replacement

## Requirement: unrelated event delegation
- Evidence: non-photo events call existingFactoryLogic
- Test: equipment alarm path remains unchanged
- Review check: handler delegates mapper-null events

## Requirement: no generated metadata
- Evidence: no random ids or timestamps are created
- Test/review: static review check for randomUUID and new Date

Business logic explanation: Traceability helps reviewers prove that the implementation still matches the original persistence-only scope.
Code logic explanation: The matrix connects each requirement to tests and review checks without generating new code.
Expected result: Advanced developers can audit coverage gaps before expanding the module.

System design decision

• Traceability matrices are valuable when generated specs, code, and tests evolve independently.
• Each requirement should have both test evidence and review evidence because some constraints are easier to inspect than execute.
• The matrix prevents later scope creep from being mislabeled as a missing test.

14. Lab 10 — Idempotent Persistence Policy Review

Developer task

Ask Kiro to define an idempotency policy for repeated photolithography drift-risk events without changing the simple in-memory workshop database.

Prompt sample

Create an idempotent persistence policy for repeated PHOTOLITHOGRAPHY_DRIFT_RISK messages. Do not implement database-specific upsert code. Explain recommended production behavior for duplicate drift_risk_event_id and duplicate factor_id within the same event.

Expected Kiro result

# Idempotent Persistence Policy

## Scope
This policy applies when the same PHOTOLITHOGRAPHY_DRIFT_RISK event may be delivered more than once by an event stream.

## Recommended production behavior
- Treat drift_risk_event_id as the summary idempotency key.
- Treat the pair drift_risk_event_id + factor_id as the factor idempotency key.
- Reprocessing the same event should not create duplicate summary records.
- Reprocessing the same factor should not create duplicate factor records.
- If the same id arrives with different source values, preserve the conflict for review instead of silently overwriting.

## Workshop boundary
- The in-memory database does not implement upsert behavior.
- The mapper should not generate ids or repair duplicates.
- Idempotency belongs to the production persistence adapter or database constraint layer.

Business logic explanation: Semiconductor event streams may redeliver messages, so production storage needs an explicit duplicate policy.
Code logic explanation: The mapper remains unchanged; idempotency is documented as a persistence-adapter concern.
Expected result: Developers understand where duplicate protection should live in a production design.

System design decision

• Idempotency is a storage concern, not a source-value mapping concern.
• Conflicting replays should be visible because silent overwrite can hide source data quality problems.
• The workshop database stays simple so learners do not confuse persistence policy with mapper logic.

15. Lab 11 — Schema Evolution Without Breaking Existing Events

Developer task

Extend the photolithography event model with one new optional source field while preserving compatibility.

Prompt sample

A future source stream may add reticle_alignment_error to PHOTOLITHOGRAPHY_DRIFT_RISK. Propose a schema evolution plan. Update the mapper and tests minimally so the field is stored directly or null. Do not require old events to contain the field.

Expected Kiro result

// Minimal mapper addition inside driftSummary
reticle_alignment_error: message.reticle_alignment_error || null,

it("stores optional reticle alignment error when present", () => {
  const result = mapPhotoDriftRiskEvent({
    event_type: "PHOTOLITHOGRAPHY_DRIFT_RISK",
    drift_risk_event_id: "photo_schema_evolution_001",
    reticle_alignment_error: "0.006",
    risk_factors: []
  });

  expect(result?.driftSummary.reticle_alignment_error).toBe("0.006");
});

it("stores null for missing reticle alignment error", () => {
  const result = mapPhotoDriftRiskEvent({
    event_type: "PHOTOLITHOGRAPHY_DRIFT_RISK",
    drift_risk_event_id: "photo_schema_evolution_002",
    risk_factors: []
  });

  expect(result?.driftSummary.reticle_alignment_error).toBeNull();
});

Business logic explanation: Photolithography risk models evolve as process engineers add new source telemetry fields.
Code logic explanation: The mapper adds one direct nullable field and keeps old events valid.
Expected result: Schema evolution is additive, testable, and compatible with existing messages.

System design decision

• Additive optional fields are safer than required fields for event-stream evolution.
• New source telemetry should still follow the direct-value-or-null rule.
• Minimal tests prove both forward compatibility and backward compatibility.

16. Lab 12 — Dependency Boundary Review

Developer task

Ask Kiro to review whether the photolithography mapper has inappropriate dependencies.

Prompt sample

Review photoDriftRiskMapper.ts for dependency boundary issues. The mapper should be pure and should not import a database client, clock, UUID generator, analytics model, dashboard publisher, or control-command client. Return PASS or FAIL with exact violations and minimal patch guidance.

Expected Kiro result

PASS criteria:
- The mapper imports no database client.
- The mapper imports no clock or UUID generator.
- The mapper imports no analytics scoring model.
- The mapper imports no dashboard or alert publisher.
- The mapper imports no automation control-command client.
- The mapper returns mapped records or null only.

FAIL example:
- Violation: mapper imports `calculatePhotoRiskScore` from analytics.
- Why it matters: persistence mapping must not calculate new risk scores.
- Minimal patch: remove the analytics import and store source process_window_risk_level directly or null.

Business logic explanation: Dependency boundaries prevent persistence code from triggering analytics, alerting, or control actions.
Code logic explanation: A pure mapper is easier to test and review because it has no side effects.
Expected result: Developers can identify dependency creep before it changes production behavior.

System design decision

• A pure mapper protects the persistence-only scope established by the spec.
• Disallowed imports are faster to review than subtle runtime side effects.
• Keeping control-command dependencies out of the mapper reduces operational risk.

17. Lab 13 — Production Readiness Review Pack

Developer task

Create a production readiness review pack for the photolithography drift-risk module.

Prompt sample

Create a production readiness review pack for the photolithography drift-risk persistence module. Include readiness checks for scope, test evidence, schema evolution, idempotency policy, operational ownership, rollback plan, and unresolved risks. Keep it concise and specific to this module.

Expected Kiro result

# Photolithography Drift Risk Production Readiness Review Pack

## Scope confirmation
- Persistence only: yes/no
- No dashboards, alerts, control actions, or derived calculations: yes/no
- Unrelated factory events delegated unchanged: yes/no

## Test evidence
- Eligible event with multiple factors: pass/fail
- Missing risk_factors behavior: pass/fail
- Missing optional fields: pass/fail
- Timeline fields remain separate: pass/fail
- Equipment alarm non-regression: pass/fail

## Schema evolution
- Additive optional fields documented: yes/no
- Old events remain valid: yes/no
- New fields follow direct-value-or-null mapping: yes/no

## Idempotency and data quality
- Summary idempotency key documented: yes/no
- Factor idempotency key documented: yes/no
- Duplicate/conflict review path documented: yes/no

## Operations
- Module owner:
- On-call escalation path:
- Rollback plan:
- Known unresolved risks:

## Decision
- Ready for controlled rollout: yes/no
- Required follow-up before rollout:

Business logic explanation: Production readiness review turns lab artifacts into deployment-oriented evidence for engineering leadership.
Code logic explanation: The pack references tests and architecture decisions instead of adding new runtime features.
Expected result: The module has a clear review path from Kiro-generated implementation to controlled rollout.

System design decision

• Readiness review combines code quality, test coverage, operations, and rollback planning.
• Explicit unresolved risks prevent hidden assumptions from becoming production surprises.
• Controlled rollout is appropriate because photolithography process-window changes can have yield impact.

18. Advanced Labs Completion Checklist

• Requirements-to-test traceability matrix created.
• Idempotent persistence policy documented without changing mapper scope.
• Additive schema evolution plan and tests created.
• Dependency boundary review prompt created.
• Production readiness review pack completed.