Build with Kiro: Factory Engineering Health Hooks Workshop

Duration: 2 hours
Audience: Professional developers, platform engineers, and senior reviewers governing AI-assisted development in semiconductor factory systems
Primary AWS AI service: Kiro
Workshop focus: Kiro hooks, review governance, and developer workflow for predictive maintenance and equipment health concentration events
Standalone outcome: Developers build hook rules and governance labs for equipment health event persistence, maintenance-event non-regression, and review quality control.

Summary

This workshop teaches developers to govern Kiro hooks for semiconductor predictive maintenance workflows. Participants define source-code safety, test coverage, review-quality, rollout, and pull-request controls for equipment health concentration events. Labs demonstrate flawed and corrected TypeScript handlers, precise hook feedback, noise tuning, event examples, and decision records that preserve source values, protect existing factory behavior, and support human review across teams.

1. Workshop Goal

This workshop adds more hands-on developer labs for using Kiro hooks in a factory engineering repository. The scenario focuses on predictive maintenance and equipment health concentration events. Developers create hooks that check code, tests, and review output for unsafe patterns before changes move to pull request review.

The workshop uses equipment health, maintenance windows, utilization, drift concentration, sensor factors, wafer-lot yield exposure, and automation control slip examples. It does not use generic application-domain examples.

Manufacturing context: equipment health concentration is reviewed together with drift signals, utilization state, and wafer-lot yield exposure because maintenance timing can affect production queue delay, rework risk, and overall yield control.

2. Learning Objectives

Developers will learn to:

1. Create Kiro hooks for equipment health event code.
2. Review flawed persistence code automatically on save.
3. Create hook rules for test coverage and review output quality.
4. Tune noisy hook rules.
5. Convert hook feedback into pull request governance.
6. Explain how hooks support but do not replace human engineering review.

3. Lab Agenda

4. Lab 1 — Hook Governance Model

Developer task

Ask Kiro to categorize hook checks for an equipment health persistence workflow.

Prompt sample

Create a hook governance model for equipment health concentration event persistence. Classify rules into source-code safety, test coverage, review-output quality, and rollout governance.

Expected Kiro result

Source-code safety:
- Exact event eligibility.
- Direct source-field storage.
- No full payload storage.
- No generated ids or timestamps.
- All health factors handled.

Test coverage:
- Eligible event persists summary and factors.
- Unrelated maintenance and alarm events are unchanged.
- Missing health_factors is safe.
- Time fields remain separate.

Review-output quality:
- PASS or FAIL.
- Exact violations.
- Minimal patch only.

Rollout governance:
- Advisory phase.
- Noise review.
- Pull request review for hook changes.

Business logic explanation: Governance separates technical rule checks from adoption process.

Code logic explanation: Kiro can use these categories to create separate hook files.

Expected result: Developers understand why multiple hooks are better than one large hook.

System design decision

1. Separating rule categories keeps hook feedback actionable. This is a system-design choice because equipment health hook governance 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. Governance rules reduce the risk of noisy or untrusted automation. For equipment health hook governance, 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. Hooks should improve review consistency but not bypass human judgment. The final design point turns the lab action into a durable engineering practice for equipment health hook governance. 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 — Equipment Health Code Hook

Create .kiro/hooks/equipment-health-code-review.md.

# Equipment Health Code Review Hook

Trigger:
Run when files matching these patterns are saved:
- `src/*Health*.ts`
- `src/*Maintenance*.ts`
- `src/*Handler.ts`

Agent action:
Review TypeScript code for equipment health concentration persistence safety.

Rules:
1. New persistence logic must run only for `event_type === "EQUIPMENT_HEALTH_CONCENTRATION"`.
2. Existing `EQUIPMENT_ALARM`, `MAINTENANCE_EVENT`, and `AUTOMATION_CONTROL_COMMAND` behavior must remain unchanged.
3. One eligible event must create one health summary record.
4. `health_factors` must be treated as an array.
5. Every health factor must create one factor record.
6. Every factor record must link to the summary using `health_event_id`.
7. Stored fields must come directly from the source event or be null.
8. Full JSON payload must not be stored.
9. Telemetry values, concentration scores, and probabilities must not be converted in persistence mapping.
10. Generated ids and generated timestamps must not be used.
11. `event_time`, `maintenance_window_time`, and `factor_time` must remain separate.
12. Do not recommend broad refactoring.

Output:
- PASS or FAIL.
- Exact violations.
- Minimal patch only.

Business logic explanation: This hook checks that equipment health persistence does not disrupt maintenance, alarm, or automation command flows.

Code logic explanation: Kiro runs the markdown instruction when matching files are saved.

Expected result: Unsafe source code receives precise FAIL feedback.

System design decision

1. Exact event eligibility prevents broad processing of unrelated events. This is a system-design choice because equipment health hook governance 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. Source-field storage protects forensic comparison with factory telemetry. For equipment health hook governance, 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. Separate time fields support maintenance planning and incident chronology. The final design point turns the lab action into a durable engineering practice for equipment health hook governance. 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 — Test Coverage Hook

Create .kiro/hooks/equipment-health-test-review.md.

# Equipment Health Test Review Hook

Trigger:
Run when files matching these patterns are saved:
- `test/*Health*.test.ts`
- `test/*Maintenance*.test.ts`
- `test/*Handler.test.ts`

Agent action:
Review tests for equipment health concentration persistence coverage.

Required coverage:
1. Eligible equipment health event creates one summary record.
2. Eligible event with at least two health factors creates multiple factor records.
3. Each factor keeps the parent `health_event_id`.
4. Missing `health_factors` creates one summary and zero factors.
5. Missing optional summary fields are stored as null.
6. Missing optional factor fields are stored as null.
7. Equipment alarm behavior remains unchanged.
8. Maintenance event behavior remains unchanged.
9. Automation control command behavior remains unchanged.
10. Event time, maintenance window time, and factor time are asserted separately.

Output:
- PASS or FAIL.
- Missing tests.
- Suggested test names.
- Minimal snippets only for missing tests.

Business logic explanation: The hook makes sure tests prove both the new equipment health feature and non-regression of existing flows.

Code logic explanation: Kiro reviews test files and reports missing behavior coverage.

Expected result: Weak tests receive actionable improvement suggestions.

System design decision

1. Test coverage should map to operational risks. This is a system-design choice because equipment health hook governance 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. Maintenance-event non-regression is critical because maintenance scheduling affects production capacity. For equipment health hook governance, 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. Suggested test names speed up developer repair. The final design point turns the lab action into a durable engineering practice for equipment health hook governance. 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 — Flawed Health Handler

Paste this flawed code into src/equipmentHealthHandler.ts.

export async function persistEquipmentHealth(message: any, db: any) {
    if (message?.event_type?.includes("HEALTH")) {
        await db.insertHealthSummary({
            health_event_id: message.health_event_id || crypto.randomUUID(),
            payload: JSON.stringify(message),
            equipment_health_concentration: Number(message.equipment_health_concentration || 0),
            created_at: new Date().toISOString()
        });

        const firstFactor = message.health_factors?.[0];
        if (firstFactor) {
            await db.insertHealthFactor({
                factor_id: firstFactor.factor_id || crypto.randomUUID(),
                health_event_id: message.health_event_id,
                sensor_name: firstFactor.sensor_name,
                sensor_value: Number(firstFactor.sensor_value || 0)
            });
        }

        return "persisted";
    }

    return "ignored";
}

Business logic explanation: This example intentionally violates the health hook rules by processing too broadly, storing full payload, generating ids, generating timestamps, converting source values, and storing only the first factor.

Code logic explanation: The hook should flag includes, crypto.randomUUID, JSON.stringify, Number, new Date, and first-factor-only handling.

Expected result: The hook returns FAIL.

Expected hook feedback

FAIL
Exact violations:
- Eligibility uses includes("HEALTH") instead of exact EQUIPMENT_HEALTH_CONCENTRATION matching.
- health_event_id can be generated.
- Full JSON payload is stored.
- equipment_health_concentration is converted to a number.
- created_at is generated.
- Only the first health factor is stored.
- factor_id can be generated.
- sensor_value is converted to a number.
Minimal patch:
- Use exact event_type check.
- Remove generated ids, payload, conversions, and created_at.
- Loop over message?.health_factors || [].
- Store direct source fields or null.

System design decision

1. Flawed examples train developers to recognize unsafe AI-generated code. This is a system-design choice because equipment health hook governance 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 hook feedback makes repair prompts more precise. For equipment health hook governance, 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. Repair should be minimal to avoid new production risk. The final design point turns the lab action into a durable engineering practice for equipment health hook governance. 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 — Corrected Equipment Health Handler

Prompt sample

Apply only the minimal patch from the equipment health code review hook. Keep direct source values or null. Do not refactor unrelated code.

Expected corrected code

export async function persistEquipmentHealth(message: any, db: any) {
    if (message?.event_type === "EQUIPMENT_HEALTH_CONCENTRATION") {
        await db.insertHealthSummary({
            health_event_id: message.health_event_id || null,
            fab_id: message.fab_id || null,
            tool_id: message.tool_id || null,
            tool_type: message.tool_type || null,
            utilization_state: message.utilization_state || null,
            equipment_health_concentration: message.equipment_health_concentration || null,
            drift_cluster_level: message.drift_cluster_level || null,
            maintenance_window_time: message.maintenance_window_time || null,
            event_time: message.event_time || null
        });

        for (const factor of message?.health_factors || []) {
            await db.insertHealthFactor({
                factor_id: factor.factor_id || null,
                health_event_id: message.health_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,
                factor_time: factor.factor_time || null
            });
        }

        return "equipment-health-concentration-persisted";
    }

    return "ignored";
}

Business logic explanation: The corrected code stores direct equipment health fields and all health factors.

Code logic explanation: Exact event matching and array looping replace unsafe broad matching and first-factor logic.

Expected result: The source hook should return PASS.

System design decision

1. Equipment health concentration is a specific event type and should not match all health-like events. This is a system-design choice because equipment health hook governance 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. All health factors must be retained for maintenance investigation. For equipment health hook governance, 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 field storage avoids mixing persistence with predictive scoring logic. The final design point turns the lab action into a durable engineering practice for equipment health hook governance. 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 — Review-Output Quality Hook

Create .kiro/hooks/review-output-quality.md.

# Review Output Quality Hook

Trigger:
Run when Kiro review notes or review markdown files are saved.

Agent action:
Check whether review output is actionable for equipment health and process-risk changes.

Rules:
1. Review output must include PASS or FAIL.
2. FAIL output must include exact violations.
3. FAIL output must include minimal patch guidance.
4. Review output must not recommend broad refactoring unless explicitly requested.
5. Review output must not introduce new business requirements.
6. Review output must distinguish source-code issues from test-coverage issues.

Output:
- PASS or FAIL.
- Missing review-output requirements.
- Minimal rewrite suggestion.

Business logic explanation: Developer teams need consistent review feedback that can be acted on quickly.

Code logic explanation: This hook evaluates the quality of review notes, not production code.

Expected result: Vague reviews are rewritten into actionable feedback.

System design decision

1. Review automation quality matters as much as code automation quality. This is a system-design choice because equipment health hook governance 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. Vague AI reviews can slow down developers. For equipment health hook governance, 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. Minimal review guidance keeps feedback aligned with the change scope. The final design point turns the lab action into a durable engineering practice for equipment health hook governance. 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 — Hook Noise Tuning

Prompt sample

Review this hook rule for noise risk: "Every equipment health file must contain at least 30 lines of comments." Should it be kept, removed, or rewritten?

Expected Kiro result

Rewrite.
The rule is noisy because comment line count does not prove safety.
Better rule:
When equipment health field mapping is introduced or changed, include a source event example and explain event_time, maintenance_window_time, and factor_time if those fields are mapped.

Business logic explanation: Noisy hooks reduce trust and can cause developers to ignore important warnings.

Code logic explanation: Kiro converts an arbitrary style rule into a meaningful documentation rule.

Expected result: Hook signal quality improves.

System design decision

1. Hooks should check operationally meaningful risks. This is a system-design choice because equipment health hook governance 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. Arbitrary style rules create alert fatigue. For equipment health hook governance, 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. Documentation requirements should be tied to field semantics. The final design point turns the lab action into a durable engineering practice for equipment health hook governance. 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 — Pull Request Governance Checklist

Prompt sample

Convert the equipment health hooks into a pull request governance checklist. Keep it concise and focused on source safety, test coverage, review quality, and rollout.

Expected Kiro output

Pull request governance checklist:
- Source code uses exact EQUIPMENT_HEALTH_CONCENTRATION eligibility.
- Existing alarm, maintenance, and automation command behavior is unchanged.
- Health summary and health factor records are persisted correctly.
- No full payload, generated ids, generated timestamps, or source-value conversions are present.
- Tests cover eligible event, multiple health factors, missing factors, optional fields, alarm, maintenance, and automation command cases.
- Review output includes PASS/FAIL, exact violations, and minimal patch guidance.
- Hook rule changes are reviewed like source code.

Business logic explanation: A PR checklist helps teams adopt hooks gradually before full enforcement.

Code logic explanation: Kiro translates hook rules into human review checks.

Expected result: Developers and reviewers share the same expectations.

System design decision

1. PR governance bridges local hook feedback and team review standards. This is a system-design choice because equipment health hook governance 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. Hook changes should be reviewed because they affect future AI-assisted development. For equipment health hook governance, 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. Human review remains responsible for final production judgment. The final design point turns the lab action into a durable engineering practice for equipment health hook governance. 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.

12. Completion Checklist

• Hook governance model created.
• Equipment health source hook created.
• Test coverage hook created.
• Flawed handler reviewed.
• Corrected handler generated.
• Review-output quality hook created.
• Noise tuning completed.
• PR governance checklist created.

13. Lab 9 — Equipment Health Event Example Lab

Prompt sample

Create a full EQUIPMENT_HEALTH_CONCENTRATION event example for code comments. Include health_event_id, fab_id, tool_id, tool_type, utilization_state, equipment_health_concentration, drift_cluster_level, maintenance_window_time, event_time, and two health_factors.

Expected event example

{
  "event_type": "EQUIPMENT_HEALTH_CONCENTRATION",
  "health_event_id": "health_evt_20260626_001",
  "fab_id": "FAB-HK-ADV-01",
  "tool_id": "DEPOSITION-PVD-04",
  "tool_type": "THIN_FILM_DEPOSITION",
  "utilization_state": "HIGH_UTILIZATION",
  "equipment_health_concentration": "0.81",
  "drift_cluster_level": "ELEVATED",
  "maintenance_window_time": "2026-06-26T18:00:00+08:00",
  "event_time": "2026-06-26T14:30:00+08:00",
  "health_factors": [
    {
      "factor_id": "health_factor_vacuum_001",
      "sensor_name": "chamber_vacuum",
      "sensor_value": "1.8e-6",
      "control_boundary": "2.0e-6",
      "unit": "torr",
      "factor_time": "2026-06-26T14:29:58+08:00"
    },
    {
      "factor_id": "health_factor_rate_002",
      "sensor_name": "deposition_rate",
      "sensor_value": "48.5",
      "control_boundary": "50.0",
      "unit": "angstrom_per_second",
      "factor_time": "2026-06-26T14:29:59+08:00"
    }
  ]
}

Business logic explanation: The event example anchors equipment health persistence in realistic factory signals and maintenance planning.

Code logic explanation: The event has one parent health id and multiple health factor ids. Time fields remain distinct.

Expected result: Kiro can use this example in code comments, tests, and review prompts.

System design decision

1. Event examples reduce schema invention. This is a system-design choice because equipment health hook governance 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. Multiple health factors reflect real equipment health concentration analysis. For equipment health hook governance, 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. Time fields support both incident analysis and maintenance planning. The final design point turns the lab action into a durable engineering practice for equipment health hook governance. 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.

14. Lab 10 — Governance Decision Record

Prompt sample

Create a short architecture decision record for why equipment health persistence stores direct source strings and does not calculate health scores in the handler.

Expected Kiro result

Decision: Equipment health persistence stores direct source fields as strings.
Context: The handler captures health concentration events for later investigation and maintenance planning.
Rationale: Calculations belong in an analytics layer. The persistence layer must preserve source values for traceability.
Consequences: The handler remains simple, tests are deterministic, and future analytics can be added without changing source-event records.

Business logic explanation: Developers need to understand why the handler avoids calculations even when health metrics look numeric.

Code logic explanation: The decision record explains why code stores values directly and keeps mapping simple.

Expected result: Reviewers can use the decision record to reject unnecessary conversions.

System design decision

1. Architecture decision records preserve reasoning beyond the workshop. This is a system-design choice because equipment health hook governance 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. Direct storage protects source-event traceability. For equipment health hook governance, 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. Separating analytics from persistence supports safer future evolution. The final design point turns the lab action into a durable engineering practice for equipment health hook governance. 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.

Additional Hands-on Developer Labs for Advanced Developers

These additional labs extend the equipment health hooks workshop with advanced developer exercises that are intentionally different from the earlier hook creation, flawed-handler repair, review-output quality, noise tuning, event example, and decision-record labs. The focus shifts to hook packaging, repository policy boundaries, staged enforcement, auditability, and conflict handling between hook rules.

15. Lab 11 — Hook Rule Manifest and Ownership Metadata

Developer task

Create a manifest that describes each equipment health hook as a governed engineering asset. The manifest should not replace the hook content. It should record ownership, trigger scope, enforcement phase, and review expectations.

Prompt sample

Create .kiro/hooks/equipment-health-hook-manifest.md for the equipment health hook set. Include hook name, trigger scope, owner role, enforcement mode, expected output contract, and required reviewer role. Do not repeat the full hook rules.

Expected Kiro result

# Equipment Health Hook Manifest

## Scope
This manifest describes governed Kiro hooks for equipment health concentration event persistence.

## Hooks

### equipment-health-code-review.md
- Owner role: Factory platform engineering
- Trigger scope: `src/*Health*.ts`, `src/*Maintenance*.ts`, `src/*Handler.ts`
- Enforcement mode: advisory during first rollout, blocking after two clean review cycles
- Output contract: PASS or FAIL, exact violations, minimal patch only
- Required reviewer role: senior factory systems developer

### equipment-health-test-review.md
- Owner role: Test automation engineering
- Trigger scope: `test/*Health*.test.ts`, `test/*Maintenance*.test.ts`, `test/*Handler.test.ts`
- Enforcement mode: advisory until missing non-regression tests are below the team threshold
- Output contract: PASS or FAIL, missing tests, suggested test names, minimal snippets only
- Required reviewer role: test owner or module maintainer

### review-output-quality.md
- Owner role: Engineering enablement
- Trigger scope: review notes and generated review markdown
- Enforcement mode: advisory
- Output contract: PASS or FAIL, missing review-output requirements, minimal rewrite suggestion
- Required reviewer role: pull request reviewer

## Change control
Hook behavior changes require pull request review because they influence future AI-assisted development.

Business logic explanation: Hook ownership prevents silent policy drift when multiple teams depend on equipment health persistence behavior.
Code logic explanation: The manifest is documentation, not executable code, but it gives reviewers a stable reference for hook intent and rollout status.
Expected result: Developers can identify who owns each hook and when it becomes advisory or blocking.

System design decision

• Hook metadata separates policy governance from source-code checks. This keeps the reviewed hook rules small while making ownership and enforcement visible.
• Enforcement mode is explicit so teams can stage adoption without surprising developers.
• Reviewer roles help prevent hook changes from being approved by people who do not understand the operational impact of maintenance and equipment health events.

16. Lab 12 — Cross-Hook Conflict Review

Developer task

Ask Kiro to review two hook rules that could conflict and propose a safe resolution.

Conflict scenario

A source-code hook says: Store direct source values or null only.
A documentation hook says: If equipment_health_concentration is present, explain whether it is above 0.80.

Prompt sample

Review this possible conflict between an equipment health source-code hook and documentation hook. The source-code hook forbids calculations in persistence mapping. The documentation hook asks developers to explain whether equipment_health_concentration is above 0.80. Resolve the conflict without allowing calculations in source code.

Expected Kiro result

Resolution: keep the source-code hook unchanged and rewrite the documentation hook.

Reason:
- The persistence mapper must not calculate thresholds or derive health states.
- Documentation may describe source field meaning, but it must not require code changes or derived fields.

Rewritten documentation rule:
When equipment_health_concentration is mapped, include a source event example and explain that threshold interpretation belongs to analytics or process-engineering review, not the persistence handler.

PASS criteria:
- The handler stores equipment_health_concentration directly or null.
- No threshold comparison is added to source code.
- Documentation explains field semantics without adding a derived status.

Business logic explanation: Conflict review prevents a documentation rule from indirectly pushing analytics logic into a persistence handler.
Code logic explanation: Kiro rewrites the weaker rule while preserving the stronger persistence safety boundary.
Expected result: Developers learn to resolve hook conflicts before they create inconsistent pull request feedback.

System design decision

• Source-code safety rules should win over ambiguous documentation rules when production behavior is at risk.
• Documentation may explain semantics but should not become a hidden requirement for derived calculations.
• Cross-hook review keeps the hook set coherent as teams add more automation.

17. Lab 13 — Staged Enforcement Simulation

Developer task

Create a staged rollout plan that moves equipment health hooks from advisory warnings to pull request gates.

Prompt sample

Create a staged enforcement plan for equipment health hooks. Start with advisory feedback, then warning-on-PR, then blocking only for high-confidence violations. Include promotion and rollback criteria.

Expected Kiro result

# Staged Enforcement Plan

## Phase 1 — Advisory local feedback
- Hooks run on save.
- Developers record false positives and missing cases.
- No pull request is blocked.

Promotion criteria:
- Hook output uses PASS or FAIL consistently.
- Minimal patch guidance is accurate for at least two review cycles.
- No high-severity false positives remain open.

## Phase 2 — Pull request warning
- Hook results are attached to pull requests.
- Reviewers must acknowledge FAIL output.
- Merges are still allowed with documented reviewer approval.

Promotion criteria:
- Repeated violations are understood and actionable.
- Non-regression tests exist for alarm, maintenance, and automation command behavior.

## Phase 3 — Blocking for high-confidence violations
Blocking violations:
- Broad event eligibility such as includes("HEALTH").
- Full payload storage.
- Generated ids or generated timestamps in persistence mapping.
- Source-value conversion in persistence mapping.

Rollback criteria:
- A hook blocks a safe production hotfix.
- A rule produces repeated false positives.
- The hook conflicts with an approved architecture decision record.

Business logic explanation: Staged enforcement protects developer productivity while improving safety around maintenance-sensitive workflows.
Code logic explanation: Only deterministic, high-confidence violations become blocking checks.
Expected result: Teams can adopt hooks without turning all AI feedback into an immediate merge gate.

System design decision

• Advisory-first rollout gives teams evidence before enforcement.
• Blocking should be limited to rules with clear operational risk and low interpretation ambiguity.
• Rollback criteria are part of safe governance, not a sign that hooks failed.

18. Lab 14 — Audit Evidence Packet for Hook-Governed Changes

Developer task

Generate a concise audit packet template for a pull request that changes equipment health persistence code.

Prompt sample

Create an audit evidence packet template for an equipment health persistence pull request governed by Kiro hooks. Include source change summary, hook results, test evidence, non-regression evidence, unresolved risks, and human reviewer sign-off.

Expected Kiro result

# Equipment Health Persistence Audit Evidence Packet

## Pull request summary
- Change purpose:
- Files changed:
- Event type affected: EQUIPMENT_HEALTH_CONCENTRATION

## Hook evidence
- Source-code safety hook: PASS/FAIL
- Test coverage hook: PASS/FAIL
- Review-output quality hook: PASS/FAIL
- Any advisory warnings:

## Test evidence
- Eligible event summary persistence tested: yes/no
- Multiple health factors tested: yes/no
- Missing health_factors tested: yes/no
- Optional null fields tested: yes/no
- Time fields tested separately: yes/no

## Non-regression evidence
- EQUIPMENT_ALARM unchanged: yes/no
- MAINTENANCE_EVENT unchanged: yes/no
- AUTOMATION_CONTROL_COMMAND unchanged: yes/no

## Human review
- Reviewer:
- Decision:
- Follow-up work:

Business logic explanation: Auditable evidence helps teams show that equipment health changes preserved traceability and did not alter unrelated factory flows.
Code logic explanation: The template turns hook output and test results into a review artifact without adding new runtime behavior.
Expected result: Reviewers have a consistent checklist for approving hook-governed changes.

System design decision

• Audit packets convert local automation feedback into durable review evidence.
• Non-regression evidence is first-class because unrelated factory events must remain stable.
• Human sign-off remains explicit because hooks support review but do not own production accountability.

19. Advanced Labs Completion Checklist

• Hook manifest created with ownership and enforcement metadata.
• Cross-hook conflict reviewed and resolved without weakening source-code safety.
• Staged enforcement plan created with promotion and rollback criteria.
• Audit evidence packet template created for equipment health pull requests.