From 2c08c778a921934581b4b7962fce2b78a8b396ec Mon Sep 17 00:00:00 2001 From: Jon Chery Date: Thu, 6 Aug 2026 15:11:12 +0000 Subject: [PATCH] =?UTF-8?q?docs(P4):=20Atelier=20skills=20mapping=20?= =?UTF-8?q?=E2=80=94=209=20skill=20files=20+=20index=20+=20BA.A=20extensio?= =?UTF-8?q?n=20(REQ-221,=20REQ-222)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit REQ-221: skills/ directory with 9 Atelier-derived skill files mapped to the BA.A citizen-developer catalog: api, security, data, testing, observability, errors, devops, infrastructure-as-code, compliance. Each names the Atelier source path, distills first-principles to the citizen-dev-relevant subset, links to agent-checklist triggers, maps to BA.A 5-skill catalog. REQ-222: docs/skills.md index (9-skill table, Atelier provenance, 8 core principles C1-C8, consumption instructions, reference-only domains, excluded domains). PROJECT.md BA.A decision extended with the Atelier-derived skill catalog reference. ---ci--- project: acdl phase: 4 milestone: v1.18 status: execute requirements: covered: [REQ-221, REQ-222] partial: [] ---/ci--- --- .ciagent/PROJECT.md | 2 +- docs/skills.md | 88 ++++++++++++++++++++++++++++++++ skills/api.md | 40 +++++++++++++++ skills/compliance.md | 49 ++++++++++++++++++ skills/data.md | 34 ++++++++++++ skills/devops.md | 37 ++++++++++++++ skills/errors.md | 34 ++++++++++++ skills/infrastructure-as-code.md | 41 +++++++++++++++ skills/observability.md | 38 ++++++++++++++ skills/security.md | 42 +++++++++++++++ skills/testing.md | 37 ++++++++++++++ 11 files changed, 441 insertions(+), 1 deletion(-) create mode 100644 docs/skills.md create mode 100644 skills/api.md create mode 100644 skills/compliance.md create mode 100644 skills/data.md create mode 100644 skills/devops.md create mode 100644 skills/errors.md create mode 100644 skills/infrastructure-as-code.md create mode 100644 skills/observability.md create mode 100644 skills/security.md create mode 100644 skills/testing.md diff --git a/.ciagent/PROJECT.md b/.ciagent/PROJECT.md index 204182d..e012f4a 100644 --- a/.ciagent/PROJECT.md +++ b/.ciagent/PROJECT.md @@ -980,7 +980,7 @@ or user-directed scope). New v1.7 decisions: | W1.A | AI-refinement trigger | **Accept recommendation.** Joint condition: N ≥ 50 consecutive changes with zero rollbacks AND no L1/L2 incident in last 6 months AND Infra & Ops unilateral override. | | W1.B | Multi-stack edge case rule | **Accept recommendation.** Permitted only for (a) DR-region mirror, (b) time-boxed experimental stack with TTL ≤ 30d, (c) explicit Infra & Ops approval with `multiStack.justification`. | | W2.A | Tag mutability for prod | **Accept recommendation (Path B).** Tag for dev/qa, SHA for prod. Platform CLI resolves tag→SHA for prod-bound workflows. Justified by the "Audit truth lives outside the repository" bet. | -| BA.A | Initial L3B skill catalog | **Accept recommendation.** 5 skills: web API, worker, scheduled job, static asset, basic observability bootstrap. Addition criteria: (a) reviewable for sensitive data, (b) expressible as a single contract submission, (c) documented use case. | +| BA.A | Initial L3B skill catalog | **Accept recommendation.** 5 skills: web API, worker, scheduled job, static asset, basic observability bootstrap. Addition criteria: (a) reviewable for sensitive data, (b) expressible as a single contract submission, (c) documented use case. **Extended v1.18 (REQ-221/222):** the BA.A 5-skill catalog is extended with 9 Atelier-derived production-grade engineering skills under `skills/` (api, security, data, testing, observability, errors, devops, infrastructure-as-code, compliance), indexed by `docs/skills.md`. The Atelier skills extend, not replace, the BA.A catalog. | | W3.D | L1/L2 standard versioning | **Decided.** Semver: interface → MAJOR, behavior → MINOR, lifecycle → PATCH (same as the v1.0 demo D-rule, lifted to the real platform). Pin model: L2 contracts pin L1 by `name@semver`; the resolver picks the highest compatible. Evolution: MAJOR bumps require a new registry entry (immutable publication); old entry enters a 12-month deprecation window. | | W3.E | Schema mandatory vs optional inputs | **Decided.** Per-env mandatory table: dev requires `stack` + `environment`; qa adds `validation.e2eSuite` + `validation.loadTest`; prod adds `runbook` + `dashboard` + `oncall`; dr adds `drDrillRef`. `inputs` map is always optional. `profile: agentic` fields (`naturalLanguageIntent`, `confidenceAtSubmission`, `agentTrace`) optional everywhere. | | BA.B | Confidence threshold tuning | **Decided.** Starting thresholds frozen for v1. Tuning begins in v1.2: track FP/FN per environment quarterly; override authority = Infra & Ops + SRE joint sign-off; any override is itself a confidence-event in the audit stream. | diff --git a/docs/skills.md b/docs/skills.md new file mode 100644 index 0000000..dd51607 --- /dev/null +++ b/docs/skills.md @@ -0,0 +1,88 @@ +# Skills — Production-Grade Guidance for the Citizen Developer + +> **Source of truth (v1.18, REQ-221, REQ-222).** The Nova skill catalog +> extends the BA.A 5-skill catalog (web API, worker, scheduled job, static +> asset, basic observability bootstrap) with Atelier-derived production- +> grade engineering principles. Each skill is a markdown file under +> `skills/` keyed to an Atelier domain path. + +## How the Citizen Developer's AI Agent Consumes Skills + +1. **Before completing a task**, read the relevant skill file(s) that + match the task's domain. +2. **Run `review/agent-checklist.md`** (from Atelier) before finishing — + the checklist items are the gate between "the code is written" and + "the task is done." +3. **Use the Atelier MCP server** (`mcp/atelier/server.py`, P5) for + agentic validation — the `atelier.validate_against_principles` tool + catches correctness/clarity/simplicity/observability gaps that + deterministic scanners (Wiz, Checkmarx, Mend) cannot. + +## The 9 Skills + +| Skill | Atelier Source | Core Principles | BA.A Mapping | +|---|---|---|---| +| [`api.md`](../skills/api.md) | `domains/api/` | C1, C2, C6 | web API | +| [`security.md`](../skills/security.md) | `domains/security/` | C1 | cross-cutting (all 5) | +| [`data.md`](../skills/data.md) | `domains/data/` | C1, C4, C6 | web API, worker, scheduled job | +| [`testing.md`](../skills/testing.md) | `domains/testing/` | C1, C5 | UAT (citizen-dev RACI) | +| [`observability.md`](../skills/observability.md) | `domains/observability/` | C7 | basic observability bootstrap | +| [`errors.md`](../skills/errors.md) | `domains/errors/` | C1, C7 | web API, worker, scheduled job | +| [`devops.md`](../skills/devops.md) | `domains/devops/` | C5, C7, C8 | scheduled job, worker | +| [`infrastructure-as-code.md`](../skills/infrastructure-as-code.md) | `domains/infrastructure-as-code/` | C1, C5, C8 | static asset | +| [`compliance.md`](../skills/compliance.md) | `domains/compliance/` | C1, C5 | cross-cutting (all 5) | + +## Atelier Provenance + +The skills are derived from [Atelier](https://git.cloudinit.dev/coreci/atelier) +— a first-principles docs-as-code engineering framework with 8 core +principles (C1–C8) and 19 domains, each with 10 derived P-rules. The +skills distill the citizen-developer-relevant subset of each domain's +first-principles, link to the agent-checklist triggers, and map to the +existing BA.A catalog. + +Atelier is vendored under `mcp/atelier/vendor/` (pinned tag, D-136) for +audit reproducibility — an agentic validation result is replayable +against the exact principles that produced it. + +## The 8 Core Principles (from Atelier) + +| # | Principle | One-line | +|---|---|---| +| C1 | Correctness | The system does what it is supposed to do, and nothing else. | +| C2 | Clarity | The intent of the code is obvious to its reader. | +| C3 | Simplicity | The solution is as simple as possible, and no simpler. | +| C4 | Locality | Decisions and their consequences live near each other. | +| C5 | Reversibility | Every decision can be undone, and the cost of undoing is known. | +| C6 | Composability | Parts combine into wholes, and the parts are reusable. | +| C7 | Observability | The system's behavior is visible to those who must understand it. | +| C8 | Economy | The system uses no more resources than the task requires. | + +Precedence: C1 > C2 > C3 > C4 > C5 > C6 > C7 > C8. Correctness is never +sacrificed. + +## Reference-Only Domains (cited inside skills, not elevated to skill files) + +These 4 Atelier domains are relevant to a citizen developer but are cited +inside the 9 skills above rather than getting their own skill file: + +- **Performance** (`domains/performance/`) — cited in `observability.md` + + `devops.md` (bounded operations, timeouts, N+1) +- **Documentation** (`domains/documentation/`) — the runbook requirement + (W3.E prod mandatory) is the documentation skill in practice +- **Concurrency** (`domains/concurrency/`) — cited in `errors.md` + + `devops.md` (bounded queues, cancellation, timeout) +- **AI/ML** (`domains/ai-ml/`) — scope: engineering discipline (data + versioning, evaluation, serving, drift), not algorithm design + +## Excluded Domains (not relevant to Nova citizen developer) + +6 Atelier domains are excluded from the Nova skill catalog (not relevant +to a citizen developer building on Nova's infrastructure platform): + +- UI/UX — Nova has no frontend (frontend-engineer deactivated, PERSONAS.md) +- Kubernetes — Nova is AWS-only this milestone (NORTH_STAR Non-Goal #7) +- GitOps + Operators — future roadmap (no GitOps reconciler today) +- Edge — not in scope (Nova is cloud, not edge) +- Messaging — not in scope (Nova deploys infra, not message brokers) +- i18n — application-level concern, not infrastructure \ No newline at end of file diff --git a/skills/api.md b/skills/api.md new file mode 100644 index 0000000..c96b233 --- /dev/null +++ b/skills/api.md @@ -0,0 +1,40 @@ +# Skill: API Design + +> **Atelier source:** `domains/api/` (first-principles + rest, graphql, +> versioning, error-responses, pagination) +> **Core principles:** C1 Correctness, C2 Clarity, C6 Composability +> **BA.A mapping:** web API skill +> **Consumer:** read this before authoring an API service contract. + +## First Principles (citizen-developer-relevant subset) + +- **Endpoints are nouns, plural, lowercase-hyphenated.** (`/customers`, + not `/getCustomer`) +- **Status codes are correct.** 200/201/204/4xx/5xx per semantics. +- **Errors are structured.** Every error response carries `code`, + `message`, `request_id` — not a stack trace. +- **Input is validated against a schema.** The contract's + `infrastructure` map is validated at resolution time; the API must + validate its own request bodies. +- **Auth is required by default.** No unauthenticated endpoints unless + explicitly declared in `policyPreconditions`. + +## Agent-Checklist Triggers + +Before completing an API task, run these (from +`review/agent-checklist.md` § API): + +- Endpoints are nouns, plural, lowercase-hyphenated +- Status codes are correct per semantics +- Errors are structured (code, message, request_id) +- Input is validated against a schema +- Auth is required by default + +## How Nova Uses This + +The submission-readiness gate (`schemas/submission-readiness.schema.json`) +checks that your contract declares `policyPreconditions`. The API skill +tells you what the platform expects your application to enforce on its +own surface (request validation, structured errors, auth). Nova does +not author your API; it deploys it. The API skill ensures the +application you deploy meets production-grade standards. \ No newline at end of file diff --git a/skills/compliance.md b/skills/compliance.md new file mode 100644 index 0000000..5c9fa47 --- /dev/null +++ b/skills/compliance.md @@ -0,0 +1,49 @@ +# Skill: Compliance + +> **Atelier source:** `domains/compliance/` (first-principles + audit-logs, +> data-retention, policy-as-code, evidence) +> **Core principles:** C1 Correctness, C5 Reversibility +> **BA.A mapping:** cross-cutting (all 5 skills) +> **Consumer:** read this before any regulated-environment submission. + +## First Principles (citizen-developer-relevant subset) + +- **Audit records are immutable once written.** Deletion/mutation is + itself an auditable incident. Nova's Decision Ledger (SQLite + hash-chain, v1.17; S3 Object Lock + JWS future) enforces this. +- **The set of auditable actions is defined a priori.** "We forgot to log + it" is a violation. The submission-readiness gate's + `policyPreconditions` declare what the platform will audit. +- **Policy violations block before the action.** Checkov runs pre-apply; + the confidence signal gates; the HITL gate stops. Compliance is + admission-time, not audit-time. +- **Evidence gathered as a byproduct of operation.** Not assembled + manually at audit time. Every pipeline run emits events into the + Decision Ledger + the evidence stream. +- **Every logged action traces to an authenticated principal.** No + shared/generic identities. The HITL approver identity (D-042) is + recorded with every prod/dr promotion. + +## Agent-Checklist Triggers (§ Compliance) + +- Audit records are immutable once written; deletion/mutation is itself + auditable (P1) +- The set of auditable actions is defined a priori (P2) +- Policy violations block before the action (admission/CI/CD-time) (P5) +- Evidence gathered as a byproduct of operation, not assembled manually + (P6) +- Every logged action traces to an authenticated principal; no + shared/generic identities (P7) + +## How Nova Uses This + +Nova's compliance posture is framework-agnostic (D-024 in Atelier; the +platform lists GDPR, SOX, SOC2, DORA — not any single framework). The +compliance skill tells you what the platform enforces (immutable audit, +pre-apply policy, evidence byproduct, authenticated principals) and what +your application must enforce (the same standards on its own surface). +The submission-readiness gate ensures your contract declares +`policyPreconditions`; the compliance skill ensures your application +respects them. This is the RACI compliance-standard equivalence made +concrete: regardless of upstream source (AI agent, SDLC, dev platform), +the same compliance standards apply to every submission. \ No newline at end of file diff --git a/skills/data.md b/skills/data.md new file mode 100644 index 0000000..2785a5d --- /dev/null +++ b/skills/data.md @@ -0,0 +1,34 @@ +# Skill: Data + +> **Atelier source:** `domains/data/` (first-principles + schema-design, +> migrations, indexing) +> **Core principles:** C1 Correctness, C4 Locality, C6 Composability +> **BA.A mapping:** web API, worker, scheduled job +> **Consumer:** read this before authoring a service with a database. + +## First Principles (citizen-developer-relevant subset) + +- **Schema reflects the domain, not the application.** Tables model + real-world entities, not ORM classes. +- **Constraints are in the schema.** NOT NULL, UNIQUE, FK — the database + enforces integrity, not the application. +- **Migration has an `up` and a `down`.** Every migration is reversible. +- **Types are domain-accurate.** UUID for IDs, TIMESTAMPTZ for timestamps, + DECIMAL for money — not string/integer/everything. +- **No `SELECT *`; no N+1.** Explicit columns; eager-load relations. + +## Agent-Checklist Triggers (§ Data) + +- Schema reflects the domain (not the application) +- Constraints are in the schema (NOT NULL, UNIQUE, FK) +- Migration has an `up` and a `down` +- Types are domain-accurate (UUID, TIMESTAMPTZ, DECIMAL for money) +- No `SELECT *`; no N+1 + +## How Nova Uses This + +Nova deploys your infrastructure (RDS, DynamoDB) but does not author your +schema. The data skill ensures the schema you bring meets production-grade +standards. The submission-readiness gate checks that your contract declares +the infrastructure; the data skill checks that the application running on +that infrastructure uses the database correctly. \ No newline at end of file diff --git a/skills/devops.md b/skills/devops.md new file mode 100644 index 0000000..6c9fa54 --- /dev/null +++ b/skills/devops.md @@ -0,0 +1,37 @@ +# Skill: DevOps + +> **Atelier source:** `domains/devops/` (first-principles + ci-cd, +> environments) +> **Core principles:** C5 Reversibility, C7 Observability, C8 Economy +> **BA.A mapping:** scheduled job, worker +> **Consumer:** read this before any deployment. + +## First Principles (citizen-developer-relevant subset) + +- **The pipeline is the process.** No manual steps. Every change flows + through the same pipeline: contract → resolver → plan → policy → + confidence → (HITL gate for qa/prod/dr) → apply → evidence. +- **Rollback path is known.** Every deployment has a documented rollback. + Terraform state is the rollback mechanism; the pipeline replans to the + prior state. +- **Config is in code, not on the server.** Environment variables, SSM + parameters, secrets — all declared, versioned, and reviewable. No + hand-configured server state. +- **Environments are parity.** dev = prod modulo data. The same contract + deploys to all environments; only the environment field changes. + +## Agent-Checklist Triggers (§ DevOps) + +- The pipeline is the process (no manual steps) +- Rollback path is known +- Config is in code, not on the server +- Environments are parity (dev = prod modulo data) + +## How Nova Uses This + +Nova IS the pipeline. The citizen developer's contract declares intent; +Nova provides the process. The DevOps skill tells you what the platform +expects from your submission: no manual steps (everything flows through +the contract), a known rollback (Terraform state), config in code (SSM +SecureString, not hand-configured servers), and environment parity (one +contract, four environments). \ No newline at end of file diff --git a/skills/errors.md b/skills/errors.md new file mode 100644 index 0000000..8cafd74 --- /dev/null +++ b/skills/errors.md @@ -0,0 +1,34 @@ +# Skill: Errors + +> **Atelier source:** `domains/errors/` (first-principles + patterns) +> **Core principles:** C1 Correctness, C7 Observability +> **BA.A mapping:** web API, worker, scheduled job +> **Consumer:** read this before authoring error handling. + +## First Principles (citizen-developer-relevant subset) + +- **Errors are not swallowed silently.** A bare `except: pass` is a bug. + Every caught error is either handled, re-raised, or logged with context. +- **Errors are specific.** Not `raise Exception("something went wrong")` + — a named exception with the what/where/why. +- **Errors preserve context.** The error carries the request ID, the + user, the action — enough to debug without reproducing. +- **Recovery is attempted when possible; fail fast when not.** Retry + transient errors with backoff; fail fast on invariant violations. + +## Agent-Checklist Triggers (§ Errors) + +- Errors are not swallowed silently +- Errors are specific (not generic "something went wrong") +- Errors preserve context (where, when, why, what) +- Recovery is attempted when possible; fail fast when not + +## How Nova Uses This + +Nova's confidence signal (D-040) uses error events as one of its 6 inputs. +The error skill ensures your application's errors are structured enough to +feed the signal: specific error types, preserved context, no silent +swallows. The platform's `report_error` Lambda action (D-055) creates a +GitHub issue on the platform repo when the pipeline fails — your +application errors should be structured enough to flow through the same +path. \ No newline at end of file diff --git a/skills/infrastructure-as-code.md b/skills/infrastructure-as-code.md new file mode 100644 index 0000000..a837279 --- /dev/null +++ b/skills/infrastructure-as-code.md @@ -0,0 +1,41 @@ +# Skill: Infrastructure as Code + +> **Atelier source:** `domains/infrastructure-as-code/` (first-principles + +> terraform, opentofu, state, modules) +> **Core principles:** C1 Correctness, C5 Reversibility, C8 Economy +> **BA.A mapping:** static asset +> **Consumer:** read this before authoring a contract that declares +> infrastructure. + +## First Principles (citizen-developer-relevant subset) + +- **Configuration is declarative, not scripted.** The contract declares + what; Terraform reconciles how. No imperative scripts in the contract. +- **Provider versions are pinned, never `latest`.** The contract's + infrastructure map may pin module versions (semver); the platform pins + provider versions. +- **State is remote with locking; never committed.** Nova manages state + in S3 + DynamoDB; the citizen developer never touches state files. +- **`plan` is reviewed before every `apply`.** The confidence signal + gates the apply; the HITL gate (qa/prod/dr) requires human attestation + before the apply proceeds. +- **No secrets in HCL; secrets via providers/stores.** Secrets live in + SSM SecureString / Secrets Manager, not in the contract or HCL. + +## Agent-Checklist Triggers (§ Infrastructure as Code) + +- Configuration is declarative, not scripted (P1) +- Provider versions are pinned, never `latest` (P5) +- State is remote with locking; never committed (P3, P8) +- `plan` is reviewed before every `apply` (P4) +- No secrets in HCL; secrets via providers/stores (P10) + +## How Nova Uses This + +Nova IS the infrastructure-as-code platform. The citizen developer +declares intent in the contract; Nova's adapter (stateless assembler, +v1.11) translates to Terraform modules; the pipeline runs plan → policy → +confidence → (HITL) → apply. The IaC skill tells you what the platform +expects from your contract: declarative inputs (not scripts), pinned +versions (not `latest`), no secrets in the contract (secrets via SSM), +and acceptance that the platform owns state + the apply path. \ No newline at end of file diff --git a/skills/observability.md b/skills/observability.md new file mode 100644 index 0000000..f89eee9 --- /dev/null +++ b/skills/observability.md @@ -0,0 +1,38 @@ +# Skill: Observability + +> **Atelier source:** `domains/observability/` (first-principles + logging, +> metrics, tracing) +> **Core principles:** C7 Observability +> **BA.A mapping:** basic observability bootstrap +> **Consumer:** read this before any production submission (W3.E requires +> `dashboard` + `oncall` for prod). + +## First Principles (citizen-developer-relevant subset) + +- **Logs are structured.** JSON with fields, not free-form text. Every + log line carries a timestamp, level, message, and context fields. +- **Every request has a correlation ID.** A request ID propagates from + ingress through every downstream call. Logs, metrics, and traces share + the same ID. +- **No high-cardinality labels in metrics.** User IDs, request IDs, and + other unbounded values go in logs/traces, not metric labels. +- **Alerts have runbooks.** Every alert links to a runbook + (`runbook` field in the submission, W3.E prod mandatory) that explains + what to do when it fires. + +## Agent-Checklist Triggers (§ Observability) + +- Logs are structured (JSON, fields) +- Every request has a correlation ID +- No high-cardinality labels in metrics +- Alerts have runbooks + +## How Nova Uses This + +The W3.E per-env mandatory table requires `runbook` + `dashboard` + +`oncall` for `prod` submissions — the submission-readiness gate enforces +this. The observability skill tells you what those artifacts must contain: +structured logs, correlation IDs, bounded metric labels, and runbook-linked +alerts. Nova provides the infrastructure (CloudWatch, the uptime +monitor); you provide the application-level observability (structured +logs, dashboards, runbooks). \ No newline at end of file diff --git a/skills/security.md b/skills/security.md new file mode 100644 index 0000000..d6a79a5 --- /dev/null +++ b/skills/security.md @@ -0,0 +1,42 @@ +# Skill: Security + +> **Atelier source:** `domains/security/` (first-principles + +> authentication, authorization, input-validation, secrets, supply-chain) +> **Core principles:** C1 Correctness (security is correctness) +> **BA.A mapping:** cross-cutting (all 5 skills) +> **Consumer:** read this before any production submission. + +## First Principles (citizen-developer-relevant subset) + +- **No secrets in code, logs, URLs, or error messages.** Secrets live in + the platform's secret store (SSM SecureString, Secrets Manager), not + your application repo. +- **Input is validated at the boundary.** Every external input (HTTP + body, query, header, file) is validated against a schema before + processing. +- **Output is encoded for its context.** HTML escaping, URL encoding, + SQL parameterization — context-appropriate, not a blanket escape. +- **Crypto uses vetted libraries.** No MD5/SHA1 for security. Use + bcrypt/argon2 for passwords, AES-GCM for encryption. +- **Authorization is checked, not assumed.** Every request verifies the + caller's authority to perform the action. + +## Agent-Checklist Triggers (§ Security) + +- No secrets in code, logs, URLs, or error messages +- Input is validated at the boundary +- Output is encoded for its context +- Crypto uses vetted libraries (no MD5/SHA1 for security) +- Authorization is checked, not assumed + +## How Nova Uses This + +The submission-readiness gate checks `policyPreconditions` (e.g., +`public-ingress: false`, `encryption_enabled: true`). The security skill +tells you what the platform enforces and what your application must +enforce on its own surface. The platform enforces infrastructure-level +security (IAM scoping, ABAC, encryption-at-rest, policy-as-code via +Checkov); you enforce application-level security (input validation, output +encoding, auth checks). The Atelier MCP server (`mcp/atelier/server.py`, +P5) can validate your code against these principles agenticly — beyond +what deterministic scanners like Wiz/Checkmarx/Mend catch. \ No newline at end of file diff --git a/skills/testing.md b/skills/testing.md new file mode 100644 index 0000000..c2b9ceb --- /dev/null +++ b/skills/testing.md @@ -0,0 +1,37 @@ +# Skill: Testing + +> **Atelier source:** `domains/testing/` (first-principles + pyramid, +> fixtures) +> **Core principles:** C1 Correctness, C5 Reversibility +> **BA.A mapping:** UAT is the citizen developer's RACI responsibility +> **Consumer:** read this before submitting for UAT. + +## First Principles (citizen-developer-relevant subset) + +- **Tests are independent.** Order doesn't matter; one test's setup + doesn't break another's. +- **Tests are deterministic.** No `Date.now()`, no `random()`, no + network calls in unit tests. +- **Edge cases are covered.** Empty, single, max, invalid — not just + the happy path. +- **A failing test names the problem.** The assertion message explains + what failed and why, not just "assertion failed". +- **The pyramid: unit → integration → e2e.** Most tests are unit; few + are e2e; the middle is integration. Don't invert the pyramid. + +## Agent-Checklist Triggers (§ Testing) + +- Tests are independent (order doesn't matter) +- Tests are deterministic (no `Date.now()`, no `random()`) +- Edge cases are covered (empty, single, max, invalid) +- A failing test names the problem specifically + +## How Nova Uses This + +Per the RACI matrix (`docs/raci.md`), the **Citizen Developer is +Responsible for User Acceptance Testing (UAT)**. The platform provides +the QA checks (policy, confidence, schema); you provide the UAT. The +testing skill ensures your UAT meets production-grade standards. The +W3.E per-env mandatory table requires `validation.e2eSuite` + +`validation.loadTest` for `qa` environment submissions — the +submission-readiness gate enforces this. \ No newline at end of file