feat: the lessons loop, and six lessons approved and published

Capture, distil, review, publish, retire (ADR-0004). Lesson candidates of
past Executions are grouped into what recurred; a lesson-curator role,
outside any Execution, proposes a lesson per group worth one; each proposal
is an issue file a person approves or rejects; an approved lesson is
written into the provider's lessons Skill, which a Specialist is given only
once it holds lessons for that Specialist's Deliverable. LESSONS_ENABLED
off runs without them, for an evaluation with and without.

The curator proposed six lessons from 21 Executions. The owner approved all
six on 2026-10-09 and they are published: five for the target architect,
one for the IaC author. None is proved by an evaluation yet.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-10-09 15:19:32 +01:00
parent 59a641fded
commit a7bc5310f3
29 changed files with 1560 additions and 6 deletions

View File

@@ -0,0 +1,24 @@
---
name: google-cloud-lessons
description: >-
Rules learned from earlier solution-architecture work on Google Cloud, one set
per Deliverable. Each was proposed from problems that recurred across
Executions, approved by a person, and kept only while evaluation shows it
helps. Use before drafting a Deliverable, to read the lessons for that
Deliverable and follow them.
metadata:
scope: every Deliverable
---
# Lessons
Each reference below holds the lessons for one Deliverable. Read the one for the Deliverable you are producing, with `load_skill_resource`, before you draft, and follow every rule in it that applies. A rule here takes precedence over a general habit; your role's instructions and the contract `submit_deliverable` checks take precedence over a rule here.
<!-- lessons:begin -->
| Deliverable | Reference | Lessons |
| --- | --- | --- |
| deployment guidance | `references/deployment_guidance.md` | 1 |
| target architecture | `references/target_architecture.md` | 5 |
<!-- lessons:end -->
This Skill is written by the lessons loop (`app/learning/`), from proposals a person approved. Do not edit it by hand: change the proposal and publish again.

View File

@@ -0,0 +1,11 @@
# Lessons: deployment guidance
Rules learned from earlier work. Follow every one that applies.
## L-05: Include Required Arguments in Alert Policies
**Rule.** Always verify and include all required arguments (such as time window definitions) when configuring nested blocks in monitoring alert policies.
**Why.** Missing required arguments in nested blocks will cause Terraform validation to fail, preventing submission.
Published 2026-10-09, from lesson proposal 05.

View File

@@ -0,0 +1,43 @@
# Lessons: target architecture
Rules learned from earlier work. Follow every one that applies.
## L-01: Create Specific Checks for All Constraints
**Rule.** Create specific Checks for every explicit constraint, metric, or capability mentioned in a requirement, rather than relying on a single broad Check.
**Why.** If detailed constraints are missed, the validation phase will reject the design for incomplete coverage, forcing a revision.
Published 2026-10-09, from lesson proposal 01.
## L-02: Assign Checks to Every Element
**Rule.** Give every Element at least one Check before you submit.
**Why.** The submission tool will reject the architecture if any Element lacks a Check, wasting an attempt.
Published 2026-10-09, from lesson proposal 02.
## L-03: Verify Resource Arguments for Checks
**Rule.** Verify that the specific resource type used for an Element actually supports the configuration argument you specify in a Check. Remember that access policies and certain configurations often require entirely separate resources.
**Why.** If a Check specifies an argument that does not exist on the resource, it cannot be implemented, forcing an architectural revision.
Published 2026-10-09, from lesson proposal 03.
## L-04: Avoid Using Values as Setting Names
**Rule.** When writing a Check for a configuration block that takes a name and value, explicitly state the block's argument name instead of writing the expected value as if it were the setting itself.
**Why.** Automated reviews may mistake specific expected values for invalid setting names, causing warnings and submission delays.
Published 2026-10-09, from lesson proposal 04.
## L-06: Do Not Mark Requirements as Not Applicable
**Rule.** Do not list Requirements in the not applicable field, as this field is strictly for Design Recommendations. Ensure every Requirement has at least one Check.
**Why.** The submission tool will reject the deliverable if a Requirement lacks a Check or is incorrectly marked as not applicable.
Published 2026-10-09, from lesson proposal 06.