@documentation-robotics/cli 0.1.0 → 0.1.7

package/dist/integrations/claude_code/skills/dr_11_apm_layer/SKILL.md

@@ -0,0 +1,273 @@
+---
+name: LAYER_11_APM
+description: Expert knowledge for APM (Observability) Layer modeling in Documentation Robotics
+triggers:
+  [
+    "APM",
+    "observability",
+    "monitoring",
+    "metrics",
+    "spans",
+    "traces",
+    "logs",
+    "OpenTelemetry",
+    "telemetry"
+  ]
+version: 0.8.3
+---
+
+# APM Layer Skill
+
+**Layer Number:** 11
+**Specification:** Metadata Model Spec v0.8.3
+**Purpose:** Defines observability using OpenTelemetry 1.0+, specifying traces, metrics, logs, and instrumentation.
+
+---
+
+## Layer Overview
+
+The APM Layer captures **application performance monitoring**:
+
+- **TRACES** - Distributed tracing with spans
+- **METRICS** - Performance and business metrics
+- **LOGS** - Structured logging
+- **INSTRUMENTATION** - Code instrumentation configuration
+- **RESOURCES** - Telemetry resource attributes
+- **ALERTING** - Alert rules and monitoring dashboards
+
+This layer uses **OpenTelemetry 1.0+** (industry standard for observability).
+
+**Central Entity:** The **Span** (unit of work in trace) is the core modeling unit.
+
+---
+
+## Pre-Extraction Verification
+
+Before extracting APM elements, verify what level of observability the codebase ACTUALLY implements. Do not model aspirational instrumentation.
+
+### Step 1: Check for OTel SDK
+
+```bash
+grep "@opentelemetry" package.json
+```
+
+**If NO OTel SDK found:**
+
+- Do NOT add `MetricInstrument`, `Span`, `TraceConfiguration`, or `ExporterConfig` elements as if they are implemented
+- ONLY model what exists: browser console logging (`LogConfiguration`), UI-displayed metrics (describe in element description that export is absent)
+- Mark all elements `provenance: inferred` and add a note in the description: "Metric concept identified; no OTel export implemented."
+
+**If OTel SDK IS found:**
+
+- Proceed with full extraction of all APM types
+
+### Step 2: Identify what observability actually exists
+
+Even without OTel, codebases may have:
+
+- Browser console error logging → `apm.logconfiguration`
+- UI-visible token/usage counters → `apm.metricinstrument` (with note: display-only, not exported)
+- Error tracking utilities → `apm.instrumentationconfig` (type: manual)
+- In-memory state tracking → `apm.metricinstrument` (inferred, note: in-memory only)
+
+### In-UI Observability vs. OTel Instrumentation
+
+| Pattern                         | Model as                                  | provenance |
+| ------------------------------- | ----------------------------------------- | ---------- |
+| `console.error()` logging       | `logconfiguration`                        | extracted  |
+| UI badge showing token count    | `metricinstrument` (note: display-only)   | inferred   |
+| Store tracks reconnection count | `metricinstrument` (note: in-memory only) | inferred   |
+| `opentelemetry.createCounter()` | `metricinstrument`                        | extracted  |
+| Prometheus export endpoint      | `exporterconfig`                          | extracted  |
+
+---
+
+## Entity Types
+
+> **CLI Introspection:** Run `dr schema types apm` for the authoritative, always-current list of node types.
+> Run `dr schema node <type-id>` for full attribute details on any type.
+
+### Core APM Entities (15 entities)
+
+| Entity Type               | Description                                                       |
+| ------------------------- | ----------------------------------------------------------------- |
+| **TraceConfiguration**    | Distributed tracing configuration                                 |
+| **Span**                  | Unit of work in distributed trace                                 |
+| **SpanEvent**             | Timestamped event within span                                     |
+| **SpanLink**              | Link between spans from different traces                          |
+| **MetricConfiguration**   | Metrics collection configuration                                  |
+| **MetricInstrument**      | Specific metric instrument (Counter, Gauge, Histogram, etc.)      |
+| **LogConfiguration**      | Structured logging configuration                                  |
+| **LogRecord**             | Individual log record                                             |
+| **LogProcessor**          | Log processing pipeline step (simple, batch, custom)              |
+| **Resource**              | Telemetry resource attributes                                     |
+| **InstrumentationScope**  | Scope of instrumentation                                          |
+| **InstrumentationConfig** | Code instrumentation configuration (library, auto/manual type)    |
+| **ExporterConfig**        | Telemetry exporter configuration (OTLP, Jaeger, Prometheus, etc.) |
+| **Alert**                 | Alert rule with severity, condition, and notification channels    |
+| **Dashboard**             | Monitoring dashboard definition (Grafana, Datadog, etc.)          |
+
+---
+
+## Type Decision Tree
+
+Use this decision tree **before assigning a type** to any APM element.
+
+- Is this an alert rule with severity and condition? → `apm.alert`
+- Is this a monitoring dashboard definition (Grafana, Datadog, etc.)? → `apm.dashboard`
+- Is this an exporter configuration (OTLP, Jaeger, Prometheus endpoint)? → `apm.exporterconfig`
+- Is this a code instrumentation configuration (library name, auto/manual)? → `apm.instrumentationconfig`
+- Is this the instrumentation scope (library version, schema URL)? → `apm.instrumentationscope`
+- Is this logging pipeline configuration (service name, minimum severity)? → `apm.logconfiguration`
+- Is this a log processor step (batch, simple, custom)? → `apm.logprocessor`
+- Is this an individual structured log record with body and severity? → `apm.logrecord`
+- Is this a metrics collection configuration (export interval, cardinality limit)? → `apm.metricconfiguration`
+- Is this a specific metric instrument (counter, gauge, histogram, observable)? → `apm.metricinstrument`
+- Is this a telemetry resource (service name, deployment environment attributes)? → `apm.resource`
+- Is this a unit of work/operation in a distributed trace? → `apm.span`
+- Is this an event that occurred within a span? → `apm.spanevent`
+- Is this a link between spans from different traces? → `apm.spanlink`
+- Is this distributed tracing configuration (sampler type, propagators)? → `apm.traceconfiguration`
+
+---
+
+## When to Use This Skill
+
+Activate when the user:
+
+- Mentions "APM", "observability", "monitoring", "telemetry"
+- Wants to add tracing, metrics, or logging
+- Asks about performance monitoring or SLOs
+- Needs to instrument code or track business metrics
+- Wants to link observability to application services
+
+---
+
+## Cross-Layer Relationships
+
+**Outgoing (APM → Other Layers):**
+
+- `instrumented-service` → Application Layer (which service is being monitored?)
+- `business-metrics` → Business Layer (business KPIs)
+
+**Incoming (Other Layers → APM):**
+
+- Application Layer → APM (services reference metrics)
+- API Layer → APM (operations set SLA targets)
+- Business Layer → APM (processes reference business metrics)
+- Data Model Layer → APM (metric instruments tracking data quality KPIs)
+- Data Store Layer → APM (query performance metrics)
+
+---
+
+## Observability Best Practices
+
+1. **Traces** - Add spans for critical operations
+2. **Metrics** - Track both technical and business metrics
+3. **Logs** - Use structured logging (JSON)
+4. **Context** - Propagate trace context across services
+5. **Sampling** - Configure appropriate sampling rates
+6. **SLOs** - Define service level objectives
+7. **Alerting** - Set up alerts for critical metrics
+8. **Cardinality** - Avoid high-cardinality attributes
+
+---
+
+## Common Commands
+
+```bash
+# Add span
+dr add apm span "Process Order"
+
+# Add metric instrument
+dr add apm metricinstrument "order_rate" --description "Order processing rate counter"
+
+# Add log record
+dr add apm logrecord "Error Log"
+
+# List APM elements
+dr list apm --type span
+
+# Validate APM layer
+dr validate --layers apm
+
+# Export APM configuration
+dr export markdown --layers apm
+```
+
+---
+
+## Example: Order Processing Span
+
+```yaml
+id: apm.span.process-order
+name: "Process Order Span"
+type: span
+properties:
+  traceId: "4bf92f3577b34da6a3ce929d0e0e4736"
+  spanId: "00f067aa0ba902b7"
+  traceState: ""
+  parentSpanId: "b9c7c989f97918e1"
+  spanKind: INTERNAL
+  startTimeUnixNano: "1544712660000000000"
+  endTimeUnixNano: "1544712661000000000"
+  droppedAttributesCount: 0
+  droppedEventsCount: 0
+  droppedLinksCount: 0
+  statusCode: OK
+  attributes:
+    order.id: "ord-12345"
+    order.total: 99.99
+    customer.id: "cust-67890"
+```
+
+---
+
+## Example: Business Metrics
+
+```yaml
+id: apm.metricinstrument.order-rate
+name: "Order Rate Metric"
+type: metricinstrument
+properties:
+  type: Counter
+  unit: orders
+  description: "Number of orders processed per minute"
+  enabled: true
+```
+
+---
+
+## Coverage Completeness Checklist
+
+Before declaring APM layer extraction complete, verify each type was considered:
+
+- [ ] `apm.alert` — Alert rule with severity and notification channels
+- [ ] `apm.dashboard` — Monitoring dashboard (Grafana, Datadog, etc.)
+- [ ] `apm.exporterconfig` — Telemetry exporter configuration (OTLP, Prometheus, etc.)
+- [ ] `apm.instrumentationconfig` — Code instrumentation configuration
+- [ ] `apm.instrumentationscope` — Instrumentation scope (library version and schema URL)
+- [ ] `apm.logconfiguration` — Logging configuration per service
+- [ ] `apm.logprocessor` — Log processing pipeline step
+- [ ] `apm.logrecord` — Individual structured log record
+- [ ] `apm.metricconfiguration` — Metrics collection configuration per service
+- [ ] `apm.metricinstrument` — Specific metric instrument (Counter, Gauge, Histogram, etc.)
+- [ ] `apm.resource` — Telemetry resource attributes (service name, environment)
+- [ ] `apm.span` — Unit of work in a distributed trace
+- [ ] `apm.spanevent` — Timestamped event within a span
+- [ ] `apm.spanlink` — Link between spans from different traces
+- [ ] `apm.traceconfiguration` — Distributed tracing configuration
+
+If any type has ZERO elements, explicitly decide:
+"This type doesn't apply to this codebase" with reasoning.
+
+---
+
+## Pitfalls to Avoid
+
+- ❌ Not propagating trace context across services
+- ❌ High-cardinality attributes (e.g., unique IDs in tags)
+- ❌ Missing business metrics (only technical metrics)
+- ❌ Not setting SLOs/SLAs
+- ❌ Over-instrumentation (too many spans)
+- ❌ Missing cross-layer links to instrumented services

package/dist/integrations/claude_code/skills/dr_12_testing_layer/SKILL.md

@@ -0,0 +1,273 @@
+---
+name: LAYER_12_TESTING
+description: Expert knowledge for Testing Layer modeling in Documentation Robotics
+triggers:
+  [
+    "testing",
+    "test coverage",
+    "test case",
+    "input partition",
+    "ISP",
+    "test strategy",
+    "coverage model"
+  ]
+version: 0.8.3
+---
+
+# Testing Layer Skill
+
+**Layer Number:** 12
+**Specification:** Metadata Model Spec v0.8.3
+**Purpose:** Defines test coverage using ISP (Input Space Partitioning) Coverage Model, specifying coverage requirements, test cases, and input partitions.
+
+---
+
+## Layer Overview
+
+The Testing Layer captures **test coverage strategy**:
+
+- **COVERAGE MODELS** - Overall test coverage requirements
+- **COVERAGE TARGETS** - What needs testing (APIs, features, data)
+- **INPUT PARTITIONS** - Partition input space for systematic coverage
+- **TEST CASES** - Concrete test case sketches
+- **CONTEXT VARIATIONS** - Test strategy variation types (functional, load, security, regression, smoke, exploratory)
+- **COVERAGE GAPS** - Identified gaps in coverage
+
+This layer uses **ISP Coverage Model** (systematic input space partitioning).
+
+**Central Entity:** The **TestCoverageModel** is the core modeling unit.
+
+---
+
+## Entity Types
+
+> **CLI Introspection:** Run `dr schema types testing` for the authoritative, always-current list of node types.
+> Run `dr schema node <type-id>` for full attribute details on any type.
+
+### Core Testing Entities (17 types)
+
+| Entity Type                 | Description                                                                    |
+| --------------------------- | ------------------------------------------------------------------------------ |
+| **TestCoverageModel**       | Root coverage model for system/component                                       |
+| **TestCoverageTarget**      | What needs testing (API, feature, data)                                        |
+| **InputSpacePartition**     | Partition of input space                                                       |
+| **PartitionValue**          | Value/range within partition                                                   |
+| **InputPartitionSelection** | Selected partition values for coverage                                         |
+| **InputSelection**          | Concrete resolved input value chosen from a partition for a specific test case |
+| **CoverageRequirement**     | Specific coverage requirement                                                  |
+| **TestCaseSketch**          | High-level test case description                                               |
+| **OutcomeCategory**         | Expected outcome categories                                                    |
+| **ContextVariation**        | Environmental/contextual variation                                             |
+| **EnvironmentFactor**       | Environment-specific factor                                                    |
+| **PartitionDependency**     | Dependencies between partitions                                                |
+| **CoverageGap**             | Identified gap in coverage                                                     |
+| **CoverageExclusion**       | Explicitly excluded coverage                                                   |
+| **CoverageSummary**         | Summary of coverage status                                                     |
+| **TargetCoverageSummary**   | Coverage summary for target                                                    |
+| **TargetInputField**        | Input field for target                                                         |
+
+---
+
+## Type Decision Tree
+
+Use this decision tree **before assigning a type** to any testing concept.
+
+```
+IS this the root coverage plan for a system, service, or feature?
+  → testing.testcoveragemodel
+
+IS this a specific thing being tested (an API operation, feature, workflow, data field)?
+  → testing.testcoveragetarget
+
+IS this a division of an input field's possible values (valid/invalid/boundary ranges)?
+  → testing.inputspacepartition
+
+IS this one specific value or boundary within a partition?
+  → testing.partitionvalue
+
+IS this a constraint that links partition values to other partitions (e.g., field B depends on field A)?
+  → testing.partitiondependency
+
+IS this a declarative selection of which partition values to exercise in a test run?
+  → testing.inputpartitionselection
+
+IS this a single concrete resolved value chosen from a partition for a specific test case?
+  → testing.inputselection
+
+IS this an overall coverage requirement (criteria like "each-choice", "pairwise")?
+  → testing.coveragerequirement
+
+IS this a concrete high-level description of a single test case?
+  → testing.testcasesketch
+
+IS this a category of expected outcomes (success, error, edge-case)?
+  → testing.outcomecategory
+
+IS this a test strategy variation type — functional, load, security, regression, smoke, or exploratory testing?
+  → testing.contextvariation
+
+IS this a concrete environmental setting with a specific value (e.g., os=Linux, locale=en-US, network=low-bandwidth)?
+  → testing.environmentfactor
+
+IS this an input field on a target that is mapped to partitions?
+  → testing.targetinputfield
+
+IS this an identified gap — something that should be tested but is not?
+  → testing.coveragegap
+
+IS this a deliberate decision to NOT test something, with documented rationale?
+  → testing.coverageexclusion
+
+IS this a rollup of coverage metrics across all targets?
+  → testing.coveragesummary
+
+IS this a per-target rollup of sketch/implementation/automation counts?
+  → testing.targetcoveragesummary
+```
+
+---
+
+## When to Use This Skill
+
+Activate when the user:
+
+- Mentions "testing", "test coverage", "test cases", "ISP"
+- Wants to define test strategy or coverage requirements
+- Asks about input partitioning or systematic testing
+- Needs to model test cases for APIs, features, or data
+- Wants to link testing to requirements or business goals
+
+---
+
+## Cross-Layer Relationships
+
+**Outgoing (Testing → Other Layers):**
+
+- `motivation.supports-goals` → Motivation Layer (quality goals)
+- `motivation.fulfills-requirements` → Motivation Layer (test requirements)
+- `business.covers-process` → Business Layer (process coverage)
+- `api.tests-operation` → API Layer (API endpoint testing)
+- `data.validates-schema` → Data Model Layer (data validation)
+- `ux.tests-view` → UX Layer (UI testing)
+
+**Incoming (Other Layers → Testing):**
+
+- Motivation Layer → Testing (requirements drive coverage)
+- API Layer → Testing (operations need test coverage)
+- Business Layer → Testing (processes need testing)
+
+---
+
+## Testing Best Practices
+
+1. **Systematic partitioning** - Use ISP to partition input space
+2. **Coverage criteria** - Define clear coverage criteria
+3. **Context variations** - Test across different contexts
+4. **Traceability** - Link tests to requirements and features
+5. **Gap analysis** - Identify and document coverage gaps
+6. **Exclusions** - Explicitly document what's not tested
+7. **Outcome categories** - Define expected outcomes clearly
+
+---
+
+## Common Commands
+
+```bash
+# Add coverage model
+dr add testing testcoveragemodel "API Coverage Model"
+
+# Add coverage target
+dr add testing testcoveragetarget "Login API Coverage"
+
+# Add test case sketch
+dr add testing testcasesketch "Valid Login Test"
+
+# List coverage models
+dr list testing --type testcoveragemodel
+
+# Validate testing layer
+dr validate --layers testing
+
+# Export coverage report
+dr export markdown --layers testing
+```
+
+---
+
+## Example: Login API Coverage Model
+
+```yaml
+id: testing.testcoveragemodel.login-api
+name: "Login API Coverage Model"
+type: testcoveragemodel
+properties:
+  version: "1.0"
+  application: application.service.auth-service
+  description: "ISP coverage model for the Login API"
+```
+
+---
+
+## Example: Login Test Coverage Target
+
+```yaml
+id: testing.testcoveragetarget.login-endpoint
+name: "Login Endpoint Coverage"
+type: testcoveragetarget
+properties:
+  targetType: api-endpoint
+  description: "POST /auth/login — validates credentials and returns a JWT"
+  priority: critical
+```
+
+---
+
+## Example: Test Case Sketch
+
+```yaml
+id: testing.testcasesketch.valid-login
+name: "Valid Login Test Case"
+type: testcasesketch
+properties:
+  status: draft
+  description: "Successful login with valid email and password returns 200 with JWT"
+  implementationFormat: automated
+```
+
+---
+
+## Coverage Completeness Checklist
+
+Before declaring testing layer extraction complete, verify each type was considered:
+
+- [ ] **testcoveragemodel** — Root coverage model exists for each major system or component under test
+- [ ] **testcoveragetarget** — All APIs, features, workflows, and data paths being tested are captured
+- [ ] **inputspacepartition** — Input fields on each target have their value space partitioned
+- [ ] **partitionvalue** — Each partition has concrete representative values and boundary cases
+- [ ] **partitiondependency** — Cross-field constraints between partitions are documented
+- [ ] **inputpartitionselection** — Coverage selections specify which partition values are exercised
+- [ ] **inputselection** — Concrete resolved inputs are selected for each test case sketch
+- [ ] **coveragerequirement** — Coverage criteria (each-choice, pairwise, etc.) are specified
+- [ ] **testcasesketch** — High-level test case sketches cover the required combinations
+- [ ] **outcomecategory** — Expected outcome categories (success, error, edge) are defined per target
+- [ ] **contextvariation** — Test strategy variation types (functional, load, security, regression, smoke, exploratory) are captured
+- [ ] **environmentfactor** — Specific factor values for each context variation are recorded
+- [ ] **targetinputfield** — Input fields on coverage targets are explicitly mapped to partitions
+- [ ] **coveragegap** — Known gaps in coverage are documented with severity and affected requirements
+- [ ] **coverageexclusion** — Deliberate out-of-scope decisions are recorded with rationale and approver
+- [ ] **coveragesummary** — An overall coverage summary exists if aggregated metrics are needed
+- [ ] **targetcoveragesummary** — Per-target coverage rollups exist for targets with tracked implementation
+
+If any type has ZERO elements, explicitly decide:
+"This type doesn't apply to this codebase" with reasoning.
+
+---
+
+## Pitfalls to Avoid
+
+- ❌ Ad-hoc testing without systematic partitioning
+- ❌ Missing context variations (only testing happy path)
+- ❌ Not documenting coverage gaps
+- ❌ No traceability to requirements
+- ❌ Missing cross-layer links to tested elements
+- ❌ Incomplete outcome categories