edercnj/x-internal-evaluate-tech-context

🔒 INTERNAL SKILL Invoked only by orchestrator/specialist skills. Not intended for direct user invocation.

Skill: x-internal-evaluate-tech-context

Purpose

Produce a deterministic hybrid technology assessment for a given execution phase and scope.

The assessment combines three sources (in precedence order):

1. Declarative configuration (--config) — explicit constraints, forced capabilities, and policy toggles.
2. Auto-detection (repository files + optional --diff) — objective evidence from changed/current artifacts.
3. Caller context (--caller-context, --capabilities) — intent and scope hints from the invoking skill.

The output is a single JSON envelope with:

• techProfile
• selectedAssets (required, recommended, optional)
• gaps
• rationale

Triggers

Internal inline invocation only:

Skill(skill: "x-internal-evaluate-tech-context",
      args: "--phase review --capabilities api,security --diff .git/DIFF.txt --caller-context '{\"interface\":\"rest\"}'")

Parameters

| Parameter | Required | Default | Description | | :--- | :--- | :--- | :--- | | --phase | M | — | Lifecycle phase: plan, implement, review, or verify | | --capabilities | M | — | Comma-separated caller capabilities (api,database,security,...) | | --config | O | auto-discovered (see Config Discovery) | Declarative overrides and rule tuning | | --diff | O | — | Optional path to unified diff or changed-files list to prioritize current-scope signals | | --caller-context | O | — | JSON string or plain text describing the caller scope (interfaces, constraints, NFRs, domain) | | --include-optional | O | false | Include optional assets in selectedAssets.optional |

Config Discovery

When --config is not provided, the skill searches for tech-context.config.json in the following paths, in priority order (first readable file wins):

| Priority | Path | Produced by | | :--- | :--- | :--- | | 1 | plans/tech-context.config.json | x-plan-architecture (legacy/default) | | 2 | plans/arch-feature-*/tech-context.config.json | x-plan-architecture | | 5 | src/patterns/tech-context.config.json | Legacy fallback |

If multiple feature-level configs (matching plans/arch-feature-*/) are found, merge them (union of forcedCapabilities, last-write-wins for scalar fields in glob order). Across priority levels, the first readable file at the lowest priority number wins (feature-scope paths 1–2 take precedence over capability 3, capability over product 4, product over legacy fallback 5). Missing config is non-fatal — falls back to auto-detection only.

Hybrid Evaluation Model

1) Normalize Inputs

• Parse --capabilities into canonical lowercase tokens.
• Parse --caller-context as JSON when possible; otherwise treat as plain text.
• Load --config when readable; missing config is non-fatal (falls back to defaults).

2) Evidence Collection

• Scan repository and optional diff for technology evidence.
• Convert each signal into {domain, signal, source, confidence}.
• Domains covered by minimum built-in rules: database, security, devops, api-events, observability.

3) Capability Resolution

Deterministic merge:

1. Start from declarative forced capabilities (config.forcedCapabilities).
2. Add auto-detected capabilities above threshold.
3. Add caller capabilities/context hints.
4. Apply explicit deny/disable rules from config.
5. Sort ascending and deduplicate.

4) Asset Selection

Resolve assets via filesystem discovery (no static matrix):

1. Glob all catalog.md files under src/patterns/:

   find src/patterns -name "catalog.md" -type f
   

2. For each catalog.md, read YAML frontmatter (stop at second ---).
3. Filter catalogs by ALL of the following:
   • artifact: catalog (ignore files without this field)
   • status != removed and status != deprecated
   • load_phase list intersects the resolved --phase
   • Capability match (any of): stack list intersects at least one resolved capability, OR type value maps to a resolved capability, OR scope includes shared
   • Grouper match: when --grouper is provided, only catalogs with matching grouper value; when omitted, all catalogs passing the other filters are included
4. Classify into required, recommended, optional using the catalog's mandatory field.
5. Stable sort (ASCII ascending) inside each bucket.

Note: This replicates the Layer A algorithm of x-internal-select-context-packs inline to avoid circular skill invocation (x-internal-select-context-packs already calls this skill).

5) Gap Analysis

Generate gaps when strong evidence implies missing controls/artifacts (for example: API present without contract tests, K8s manifests without probes, security scope without pentest artifacts).

Minimum Detection Rules (Extensible)

These rules are the baseline only; declarative config may extend/override patterns without changing this skill.

| Domain | Evidence examples (files/content/diff) | Detection outcome | | :--- | :--- | :--- | | database | **/migrations/**, *.sql, ORM configs, datasource URLs, DDL tokens (CREATE TABLE, ALTER TABLE) | Enable database; increase confidence with schema + migration co-occurrence | | security / pentest | security/**, DAST/SAST/pentest scripts, ZAP/Nuclei/OWASP artifacts, auth/policy markers (JWT/OAuth/CSP/rate-limit) | Enable security; flag pentest coverage expectation when runtime-facing changes exist | | devops / k8s | Dockerfile, docker-compose*, k8s/*.y*ml, helm/**, CI workflows | Enable devops; elevate k8s sub-signal when manifest kinds (Deployment/Service/Ingress) appear | | api-events | OpenAPI/Swagger/AsyncAPI/Proto specs, route/controller handlers, event schemas, broker configs (Kafka/Rabbit/NATS) | Enable api-events; tag subtype api, events, or both | | observability | OpenTelemetry setup, Prometheus/Grafana/Loki configs, tracing/metrics/logging middleware | Enable observability; raise gap if telemetry is absent in high-change backend scope | | graphql | *.graphql, *.gql, spring-graphql, @QueryMapping, apollo-server, graphql-java | Enable graphql, api | | grpc | *.proto, @GrpcService, grpc-spring-boot-starter, io.grpc, protoc build config, buf/protoc build files, gRPC channel/stub config | Enable grpc, api | | resilience | resilience4j.*, @CircuitBreaker, @Retry, @Bulkhead, @TimeLimiter, io.github.resilience4j | Enable resilience | | supply-chain | cosign, trivy.yaml, .snyk, slsa-github-generator, sbom*, syft, grype, OSSF scorecard, dependency audit scripts | Enable supply-chain, security | | terraform | *.tf, *.tfvars, terraform.lock.hcl, .terraform/, terraform { block, backend "s3", backend "azurerm", Terraform provider blocks | Enable terraform, devops | | websocket | @MessageMapping, SockJS, WebSocketHandler, WebSocketConfigurer, ws://, socket.io | Enable websocket, api | | cache | Redis config files, spring.cache.*, @Cacheable, CacheManager, Caffeine, Jedis/Lettuce imports, aws-elastic-cache/elasticache/memorystore references | Enable cache | | messaging / events | Kafka configs (kafka.bootstrap-servers, @KafkaListener), RabbitMQ, @SqsListener, SQS/SNS/Service Bus/Pub-Sub references, AsyncAPI specs | Enable events, messaging | | service-mesh | Istio/Linkerd/Consul manifests, VirtualService, DestinationRule, PeerAuthentication, ServiceEntry, mesh sidecar annotations | Out of scope for this repository (do not enable capabilities) | | secrets | Vault config/client, ExternalSecret CRDs (ESO), @Value("${...}") with secrets references, aws-secretsmanager/azure-key-vault/gcp-secret-manager references | Enable secrets, security | | compliance | LGPD/GDPR/PCI/HIPAA/SOC2 tokens in docs/configs, audit log patterns, data classification markers | Enable compliance, security | | local-dev | docker-compose.yml/docker-compose.override.yml, .devcontainer/, minikube start scripts, localstack/azurite container configs | Enable local-dev, devops |

Version Detection Rules

This skill MUST attempt version detection for active capabilities. Version signals are extracted from build files and reported in techProfile.versions.

| Technology | Source Files | Extraction Rule | | :--- | :--- | :--- | | Java | pom.xml → <java.version> or <maven.compiler.source> or <properties><java.version>; build.gradle → java { sourceCompatibility } or toolchain { languageVersion } | Extract major version number (e.g., 21) | | Spring Boot | pom.xml → <parent><version> under spring-boot-starter-parent; build.gradle → id 'org.springframework.boot' version | Extract as major.minor dir key: 3.2.x → 3.x, 2.7.5 → 2.7.x | | Node.js | package.json → engines.node; .nvmrc; .node-version | Extract major (e.g., 20) | | PostgreSQL | docker-compose.yml → postgres image tag; application.yml → spring.datasource.url host annotation; flyway.conf | Extract major (e.g., 14, 16) | | AWS RDS PostgreSQL | application.yml/infra manifests with RDS endpoint patterns (rds.amazonaws.com) and postgres driver | Extract major when explicit, fallback 16 | | AWS Aurora (PostgreSQL) | Aurora endpoint patterns (cluster-*.rds.amazonaws.com) + postgres driver | Extract major when explicit, fallback 16 | | Oracle | Oracle datasource/driver hints (jdbc:oracle, oracle.jdbc) | Extract major tag (e.g., 19c) | | AWS RDS Oracle | RDS endpoint patterns with Oracle datasource/driver hints | Extract major tag (e.g., 19c) | | MongoDB | docker-compose.yml → mongo image tag; Spring Boot spring.data.mongodb version | Extract major (e.g., 7, 6) | | DynamoDB | aws-java-sdk-dynamodb or @aws-sdk/client-dynamodb present | Emit 2024 (current API, no storage version) | | Kubernetes | k8s/*.yaml → apiVersion annotations; src/workflows → kubectl version | Extract minor version (e.g., 1.28) | | Kafka | docker-compose.yml → confluentinc/cp-kafka image tag; spring.kafka.producer.client-id with version | Extract major.minor (e.g., 3.7) |

Determinism Rules

For identical inputs (phase, capabilities, config, diff, caller-context) the skill MUST produce byte-stable JSON:

1. Canonical lowercase domains/capabilities.
2. Stable tie-breakers (confidence desc, then domain asc, then signal asc).
3. Sorted arrays in all output collections.
4. No timestamps, random IDs, or environment-dependent ordering in stdout.
5. versions field MUST always be present with all known technology keys; emit null for undetected technologies.

Output Contract

Emit exactly one JSON object (single line) to stdout:

{
  "techProfile": {
    "phase": "review",
    "capabilities": ["api", "security"],
    "detectedDomains": ["api-events", "security"],
    "confidence": {
      "api-events": 0.91,
      "security": 0.74
    },
    "versions": {
      "java": "21",
      "springBoot": "3.x",
      "node": null,
      "postgres": "14",
      "awsRdsPostgres": null,
      "awsAurora": null,
      "oracle": null,
      "awsRdsOracle": null,
      "mongodb": null,
      "dynamodb": null,
      "k8s": "1.28",
      "kafka": null
    },
    "inputsUsed": {
      "config": true,
      "diff": true,
      "callerContext": true
    }
  },
  "selectedAssets": {
    "required": [
      "src/patterns/shared/security/catalog.md"
    ],
    "recommended": [
      "src/patterns/shared/api/catalog.md"
    ],
    "optional": []
  },
  "gaps": [
    {
      "id": "gap-api-no-contract-tests",
      "domain": "api-events",
      "severity": "medium",
      "message": "API surface detected without contract-testing evidence.",
      "suggestedAction": "Include contract-test assets for the active API scope."
    }
  ],
  "rationale": [
    {
      "domain": "api-events",
      "source": "auto-detection",
      "confidence": 0.91,
      "evidence": ["openapi.yaml", "src/routes/"]
    },
    {
      "domain": "security",
      "source": "caller-context",
      "confidence": 0.62,
      "evidence": ["capabilities:security"]
    }
  ]
}

Error Contract

On failure, stdout MUST still emit deterministic JSON with the same top-level keys plus error, and exit non-zero.

| Exit code | Name | Condition | Required error.code | | :--- | :--- | :--- | :--- | | 64 | USAGE_ERROR | Missing/invalid required parameters | TECH_CONTEXT_USAGE_ERROR | | 65 | INVALID_PHASE | --phase outside allowed enum | TECH_CONTEXT_INVALID_PHASE | | 66 | CONFIG_INVALID | Config unreadable or malformed JSON schema | TECH_CONTEXT_CONFIG_INVALID | | 67 | DIFF_UNREADABLE | --diff path provided but not readable/parsible | TECH_CONTEXT_DIFF_UNREADABLE | | 69 | DETECTION_FAILURE | Internal detection pipeline error | TECH_CONTEXT_DETECTION_FAILURE | | 70 | ASSET_RESOLUTION_FAILURE | Unable to resolve assets for resolved capabilities | TECH_CONTEXT_ASSET_RESOLUTION_FAILURE |

Error payload shape:

{
  "techProfile": null,
  "selectedAssets": { "required": [], "recommended": [], "optional": [] },
  "gaps": [],
  "rationale": [],
  "error": {
    "code": "TECH_CONTEXT_CONFIG_INVALID",
    "message": "Config file is malformed JSON: src/patterns/tech-context.config.json"
  }
}

Consumer Contract

Caller skills MUST:

1. Pass an explicit --phase.
2. Pass relevant --capabilities from their current scope.
3. Forward active diff/context whenever available.
4. Consume selectedAssets.required as mandatory context load.
5. Treat gaps as actionable review/planning findings, not as fatal unless policy requires.
6. When selecting versioned pattern files, read techProfile.versions.{technology} to choose the correct versioned directory. If null, fall back to the highest available version directory.

Integration Notes

This skill is intentionally standalone in this story scope. No mandatory coupling to other skills is required yet; downstream orchestrators may adopt it incrementally.