@harness-engineering/cli 1.14.0 → 1.16.0

package/dist/agents/skills/cursor/harness-impact-analysis/SKILL.md

@@ -0,0 +1,184 @@
+# Harness Impact Analysis
+
+> Graph-based impact analysis. Answers: "if I change X, what breaks?"
+
+## When to Use
+
+- Before merging a PR — understand the blast radius of changes
+- When planning a refactoring — know what will be affected
+- When a test fails — trace backwards to find what change caused it
+- When `on_pr` triggers fire
+- NOT for understanding code (use harness-onboarding or harness-code-review)
+- NOT for finding dead code (use cleanup-dead-code)
+
+## Prerequisites
+
+A knowledge graph at `.harness/graph/` enables full analysis. If no graph exists,
+the skill uses static analysis fallbacks (see Graph Availability section).
+Run `harness scan` to enable graph-enhanced analysis.
+
+### Graph Availability
+
+Before starting, check if `.harness/graph/graph.json` exists.
+
+**If graph exists:** Check staleness — compare `.harness/graph/metadata.json`
+scanTimestamp against `git log -1 --format=%ct` (latest commit timestamp).
+If graph is more than 2 commits behind (`git log --oneline <scanTimestamp>..HEAD | wc -l`),
+run `harness scan` to refresh before proceeding. (Staleness sensitivity: **High**)
+
+**If graph exists and is fresh (or refreshed):** Use graph tools as primary strategy.
+
+**If no graph exists:** Output "Running without graph (run `harness scan` to
+enable full analysis)" and use fallback strategies for all subsequent steps.
+
+## Process
+
+### Phase 1: IDENTIFY — Determine Changed Files
+
+1. **From diff**: If a git diff is available, parse it to extract changed file paths.
+2. **From input**: If file paths are provided directly, use those.
+3. **From git**: If neither, use `git diff --name-only HEAD~1` to get recent changes.
+
+### Phase 2: ANALYZE — Query Graph for Impact
+
+For each changed file:
+
+1. **Direct dependents**: Use `get_impact` MCP tool to find all files that import or call the changed file.
+
+   ```
+   get_impact(filePath="src/services/auth.ts")
+   → tests: [auth.test.ts, integration.test.ts]
+   → docs: [auth-guide.md]
+   → code: [routes/login.ts, middleware/verify.ts, ...]
+   ```
+
+2. **Transitive dependents**: Use `query_graph` with depth 3 to find indirect consumers.
+
+   ```
+   query_graph(rootNodeIds=["file:src/services/auth.ts"], maxDepth=3, includeEdges=["imports", "calls"])
+   ```
+
+3. **Documentation impact**: Use `get_relationships` to find `documents` edges pointing to changed nodes.
+
+4. **Test coverage**: Identify test files connected via `imports` edges. Flag changed files with no test coverage.
+
+5. **Design token impact**: When the graph contains `DesignToken` nodes, use `query_graph` with `USES_TOKEN` edges to find components that consume changed tokens.
+
+   ```
+   query_graph(rootNodeIds=["designtoken:color.primary"], maxDepth=2, includeEdges=["uses_token"])
+   → components: [Button.tsx, Card.tsx, Header.tsx, ...]
+   ```
+
+   If a changed file is `design-system/tokens.json`, identify ALL tokens that changed and trace each to its consuming components. This reveals the full design blast radius of a token change.
+
+6. **Design constraint impact**: When the graph contains `DesignConstraint` nodes, check if changed code introduces new `VIOLATES_DESIGN` edges.
+
+#### Fallback (without graph)
+
+When no graph is available, use static analysis to approximate impact:
+
+1. **Parse imports**: For each changed file, grep all source files for `import.*from.*<changed-file>` and `require.*<changed-file>` patterns to find direct dependents.
+2. **Follow imports 2 levels deep**: For each direct dependent found, repeat the import grep to find second-level dependents. Stop at 2 levels (fallback cannot reliably trace deeper).
+3. **Find test files by naming convention**: For each changed file `foo.ts`, search for:
+   - `foo.test.ts`, `foo.spec.ts` (same directory and `__tests__/` directory)
+   - `*.test.*` and `*.spec.*` files that import the changed file (from step 1)
+4. **Find docs by path matching**: Grep `docs/` directory for references to the changed module name (filename without extension).
+5. **Group results** the same as the graph version: tests, docs, code, other. Note the count of files found.
+
+> Fallback completeness: ~70% — misses transitive deps beyond 2 levels.
+
+### Phase 3: ASSESS — Risk Assessment and Report
+
+1. **Impact score**: Calculate based on:
+   - Number of direct dependents (weight: 3x)
+   - Number of transitive dependents (weight: 1x)
+   - Whether affected code includes entry points (weight: 5x)
+   - Whether tests exist for the changed code (no tests = higher risk)
+   - Whether design tokens are affected (weight: 2x — token changes cascade to all consumers)
+
+2. **Risk tiers**:
+   - **Critical** (score > 50): Changes affect entry points or >20 downstream files
+   - **High** (score 20-50): Changes affect multiple modules or shared utilities
+   - **Medium** (score 5-20): Changes affect a few files within the same module
+   - **Low** (score < 5): Changes are isolated with minimal downstream impact
+
+3. **Output report**:
+
+   ```
+   ## Impact Analysis Report
+
+   ### Changed Files
+   - src/services/auth.ts (modified)
+   - src/types/user.ts (modified)
+
+   ### Impact Summary
+   - Direct dependents: 8 files
+   - Transitive dependents: 23 files
+   - Affected tests: 5 files
+   - Affected docs: 2 files
+   - Risk tier: HIGH
+
+   ### Affected Tests (must run)
+   1. tests/services/auth.test.ts (direct)
+   2. tests/routes/login.test.ts (transitive)
+   3. tests/integration/auth-flow.test.ts (transitive)
+
+   ### Affected Documentation (may need update)
+   1. docs/auth-guide.md → documents src/services/auth.ts
+   2. docs/api-reference.md → documents src/types/user.ts
+
+   ### Downstream Consumers
+   1. src/routes/login.ts — imports auth.ts
+   2. src/middleware/verify.ts — imports auth.ts
+   3. src/routes/signup.ts — imports user.ts (transitive via auth.ts)
+
+   ### Affected Design Tokens (when tokens change)
+   1. color.primary → used by 12 components
+   2. typography.body → used by 8 components
+   ```
+
+## Harness Integration
+
+- **`harness scan`** — Recommended before this skill for full graph-enhanced analysis. If graph is missing, skill uses static analysis fallbacks.
+- **`harness validate`** — Run after acting on findings to verify project health.
+- **Graph tools** — This skill uses `query_graph`, `get_impact`, and `get_relationships` MCP tools.
+
+## Success Criteria
+
+- Impact report generated with a risk tier (Critical / High / Medium / Low)
+- All affected test files listed with direct vs transitive classification
+- All affected documentation files listed with relationship context
+- Report follows the structured output format
+- All findings are backed by graph query evidence (with graph) or systematic static analysis (without graph)
+
+## Examples
+
+### Example: Analyzing a Change to auth.ts
+
+```
+Input: git diff shows src/services/auth.ts modified
+
+1. IDENTIFY — Extract changed file: src/services/auth.ts
+2. ANALYZE  — get_impact(filePath="src/services/auth.ts")
+              query_graph(rootNodeIds=["file:src/services/auth.ts"], maxDepth=3)
+              Results: 8 direct dependents, 23 transitive, 5 tests, 2 docs
+3. ASSESS   — Impact score: 34 (High tier)
+              - Entry points affected: no
+              - Tests exist: yes (5 files)
+
+Output:
+  Risk tier: HIGH
+  Must-run tests: auth.test.ts, login.test.ts, auth-flow.test.ts
+  Docs to update: auth-guide.md, api-reference.md
+  Downstream consumers: 8 files across 3 modules
+```
+
+## Gates
+
+- **Graph preferred, fallback available.** If no graph exists, use fallback strategies (import parsing, naming conventions, path matching). Do not stop — produce the best analysis possible with available tools.
+- **No risk assessment without data.** Use graph queries when available; use import parsing and naming conventions when not. If neither approach yields data, state what is missing.
+
+## Escalation
+
+- **When graph is stale**: If the graph's last scan timestamp is older than the most recent commit, warn that results may be incomplete and suggest re-scanning.
+- **When impact is critical**: If risk tier is Critical, recommend a thorough code review and full test suite run before merging.

package/dist/agents/skills/cursor/harness-impact-analysis/skill.yaml

@@ -0,0 +1,45 @@
+name: harness-impact-analysis
+version: "1.0.0"
+description: Graph-based impact analysis — answers "if I change X, what breaks?"
+cognitive_mode: analytical-reporter
+triggers:
+  - manual
+  - on_pr
+platforms:
+  - claude-code
+  - gemini-cli
+tools:
+  - Bash
+  - Read
+  - Glob
+  - Grep
+cli:
+  command: harness skill run harness-impact-analysis
+  args:
+    - name: path
+      description: Project root path
+      required: false
+    - name: files
+      description: Comma-separated list of changed files
+      required: false
+mcp:
+  tool: run_skill
+  input:
+    skill: harness-impact-analysis
+    path: string
+type: rigid
+tier: 2
+phases:
+  - name: identify
+    description: Identify changed files from diff or input
+    required: true
+  - name: analyze
+    description: Query graph for impact of each changed file
+    required: true
+  - name: assess
+    description: Rank findings by risk and generate report
+    required: true
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/cursor/harness-incident-response/SKILL.md

@@ -0,0 +1,223 @@
+# Harness Incident Response
+
+> Runbook generation, postmortem analysis, and SLO/SLA tracking. Diagnoses incidents by tracing symptoms through services, produces structured postmortems, and maintains error budget accounting.
+
+## When to Use
+
+- After a production incident to generate a structured postmortem with timeline and action items
+- To create or audit runbooks for critical services and failure scenarios
+- To define, track, or adjust SLOs/SLAs and monitor error budget consumption
+- NOT for real-time incident coordination (use PagerDuty, OpsGenie, or incident.io for live response)
+- NOT for infrastructure provisioning or remediation (use harness-infrastructure-as-code)
+- NOT for performance benchmarking (use harness-load-testing for capacity planning)
+
+## Process
+
+### Phase 1: ASSESS -- Determine Scope and Severity
+
+1. **Identify the incident signal.** Scan available evidence to determine what triggered the investigation:
+   - Check for existing incident reports in `docs/incidents/` or `docs/postmortems/`
+   - Look for recent error spikes in log files, monitoring configs, or alerting rules
+   - Review recent deployments via `git log --oneline --since="48 hours ago"` for correlated changes
+
+2. **Map affected services.** Trace the blast radius from the incident signal:
+   - Identify the originating service from error messages or alert metadata
+   - Walk dependency chains using import graphs or service manifests (`docker-compose.yml`, `kubernetes/`, service mesh configs)
+   - List all downstream services that depend on the affected component
+
+3. **Classify severity.** Apply the project's severity matrix if one exists in `docs/runbooks/severity-matrix.md`. Otherwise, use standard classification:
+   - **SEV1:** Complete service outage, data loss, or security breach affecting all users
+   - **SEV2:** Major feature degradation affecting a significant subset of users
+   - **SEV3:** Minor feature degradation with workaround available
+   - **SEV4:** Cosmetic issue or internal tooling degradation
+
+4. **Establish timeline boundaries.** Determine:
+   - When the incident started (first error, first alert, or first user report)
+   - When it was detected (MTTD -- Mean Time to Detect)
+   - When mitigation began
+   - When the incident was resolved (MTTR -- Mean Time to Recover)
+
+5. **Check for existing runbooks.** Search `docs/runbooks/` and `runbooks/` for procedures matching the affected service or failure mode. If a runbook exists, evaluate whether it was followed and whether it was effective.
+
+---
+
+### Phase 2: INVESTIGATE -- Trace Root Cause
+
+1. **Correlate with recent changes.** Run `git log --oneline --since="7 days ago"` and cross-reference commits with the incident timeline. Flag commits that touched affected services or their dependencies.
+
+2. **Analyze error patterns.** Search the codebase for error handling related to the failure:
+   - Grep for error messages, exception types, or error codes mentioned in the incident
+   - Check retry logic, timeout configurations, and circuit breaker states
+   - Identify whether the failure was transient (timeout, network) or persistent (logic error, data corruption)
+
+3. **Trace data flow.** Map the request path from entry point to failure point:
+   - Identify API endpoints, message queues, or cron jobs involved
+   - Check database queries and external API calls along the path
+   - Look for missing validation, unhandled edge cases, or race conditions
+
+4. **Identify contributing factors.** Distinguish between root cause and contributing factors:
+   - Root cause: the single change or condition that directly caused the failure
+   - Contributing factors: conditions that allowed the failure to reach production (missing tests, inadequate monitoring, deployment without canary)
+
+5. **Validate the hypothesis.** Confirm the root cause by checking:
+   - Does reverting the identified change (or simulating the revert) resolve the issue?
+   - Does the failure reproduce under the identified conditions?
+   - Are there other incidents with the same root cause pattern?
+
+---
+
+### Phase 3: DOCUMENT -- Generate Artifacts
+
+1. **Generate the postmortem report.** Create a structured document in `docs/postmortems/YYYY-MM-DD-<slug>.md` with these sections:
+   - **Summary:** One-paragraph description of what happened, impact, and duration
+   - **Timeline:** Chronological list of events from first signal to resolution
+   - **Root Cause:** Clear statement of what went wrong and why
+   - **Contributing Factors:** Conditions that enabled the failure
+   - **Impact:** User-facing impact, data impact, SLO impact, revenue impact if applicable
+   - **Detection:** How the incident was detected and time to detection
+   - **Mitigation:** Steps taken to resolve the incident
+   - **Action Items:** Numbered list with owner, priority, and due date
+
+2. **Create or update runbooks.** For each failure mode identified:
+   - If no runbook exists, create one in `docs/runbooks/<service>-<failure-mode>.md`
+   - Structure: Symptoms, Diagnosis Steps, Mitigation Steps, Escalation Path, Recovery Verification
+   - Include concrete commands (kubectl, database queries, API calls) not just prose descriptions
+   - Reference monitoring dashboards and alert names
+
+3. **Update the incident log.** If `docs/incidents/index.md` exists, append the new incident with date, severity, MTTR, and link to the postmortem.
+
+4. **Tag related code.** Add or update `// INCIDENT-YYYY-MM-DD: <description>` comments at the code locations involved in the root cause. This creates a searchable history of incident-prone code.
+
+---
+
+### Phase 4: IMPROVE -- SLO Adjustments and Prevention
+
+1. **Calculate SLO impact.** If `slo.yaml` or equivalent SLO definitions exist:
+   - Determine how much error budget the incident consumed
+   - Calculate remaining error budget for the current window
+   - If error budget is exhausted, flag that feature development should pause for reliability work
+
+2. **Evaluate alerting effectiveness.** For each alert that fired (or should have fired):
+   - Was the alert timely? Compare alert time to incident start time
+   - Was the alert actionable? Did it point to the right service and include enough context?
+   - Were there false negatives? Identify monitoring gaps that should have caught the issue earlier
+
+3. **Propose SLO adjustments.** Based on the incident analysis:
+   - If the SLO was violated but the impact was acceptable, the SLO may be too tight
+   - If the SLO was not violated but users were impacted, the SLO may be too loose
+   - Recommend specific SLI (Service Level Indicator) thresholds with justification
+
+4. **Generate preventive action items.** Categorize actions by type:
+   - **Code fixes:** Specific bugs or missing validations to address
+   - **Testing gaps:** Missing integration tests, chaos tests, or load tests to add
+   - **Monitoring improvements:** New alerts, dashboards, or SLIs to implement
+   - **Process improvements:** Deployment safeguards, runbook updates, or on-call training
+   - **Architecture changes:** Circuit breakers, bulkheads, or redundancy to add
+
+5. **Produce the improvement summary.** Output a prioritized action list with effort estimates and expected impact on MTTD and MTTR.
+
+---
+
+## Harness Integration
+
+- **`harness skill run harness-incident-response`** -- Primary CLI entry point. Runs all four phases.
+- **`harness validate`** -- Run after generating documents to ensure project structure is intact.
+- **`harness check-deps`** -- Verify service dependency declarations match the incident trace.
+- **`emit_interaction`** -- Used at severity classification (checkpoint:decision) to confirm severity with the operator before proceeding.
+- **`Glob`** -- Discover existing runbooks, postmortems, and SLO definitions.
+- **`Grep`** -- Search for error patterns, alert configurations, and incident-related code comments.
+- **`Write`** -- Generate postmortem reports and runbook documents.
+- **`Edit`** -- Update existing runbooks and incident indexes.
+
+## Success Criteria
+
+- Postmortem document is complete with all required sections (summary, timeline, root cause, action items)
+- Timeline includes MTTD and MTTR calculations with specific timestamps
+- Root cause is a specific, falsifiable statement (not "the system failed")
+- Action items have owners, priorities, and due dates
+- Runbooks contain concrete commands, not just descriptive prose
+- SLO impact is quantified against the error budget when SLO definitions exist
+
+## Examples
+
+### Example: Node.js API Timeout Incident with Datadog Alerts
+
+```
+Phase 1: ASSESS
+  Signal: Datadog alert "api-gateway p99 latency > 2000ms" fired at 14:32 UTC
+  Affected: api-gateway -> user-service -> PostgreSQL
+  Severity: SEV2 (major degradation, 40% of requests timing out)
+  MTTD: 4 minutes (alert fired 4 min after first error)
+  MTTR: 47 minutes (resolved at 15:19 UTC)
+
+Phase 2: INVESTIGATE
+  Correlated change: commit abc123 "add user preferences join" deployed at 14:25 UTC
+  Root cause: N+1 query in GET /api/users/:id/preferences — new LEFT JOIN
+    on unindexed column `preferences.user_id` caused full table scan
+  Contributing factors:
+    - No query performance test for the preferences endpoint
+    - Missing database index on preferences.user_id
+    - No circuit breaker between api-gateway and user-service
+
+Phase 3: DOCUMENT
+  Created: docs/postmortems/2026-03-15-user-service-timeout.md
+  Created: docs/runbooks/user-service-database-slow-query.md
+  Updated: docs/incidents/index.md
+
+Phase 4: IMPROVE
+  SLO impact: Consumed 12% of monthly error budget (88% remaining)
+  Action items:
+    1. [P0] Add index on preferences.user_id (owner: @backend, due: 2026-03-16)
+    2. [P1] Add query execution time assertions to integration tests (owner: @backend, due: 2026-03-22)
+    3. [P1] Add circuit breaker on api-gateway -> user-service (owner: @platform, due: 2026-03-22)
+    4. [P2] Add Datadog query performance monitor for user-service (owner: @sre, due: 2026-03-29)
+```
+
+### Example: Kubernetes Pod CrashLoopBackOff with PagerDuty Escalation
+
+```
+Phase 1: ASSESS
+  Signal: PagerDuty incident #4521 — payment-service pods in CrashLoopBackOff
+  Affected: payment-service -> Stripe API -> order-service (downstream)
+  Severity: SEV1 (payment processing completely down)
+  MTTD: 2 minutes (PagerDuty auto-detected from Kubernetes health checks)
+  MTTR: 23 minutes
+
+Phase 2: INVESTIGATE
+  Root cause: Environment variable STRIPE_WEBHOOK_SECRET rotated in Vault
+    but payment-service pods were not restarted to pick up new value.
+    Stripe signature verification failed on all incoming webhooks, causing
+    panic in the webhook handler (no error recovery).
+  Contributing factors:
+    - Vault secret rotation did not trigger pod restart
+    - Webhook handler used panic instead of returning error
+    - No runbook for secret rotation procedures
+
+Phase 3: DOCUMENT
+  Created: docs/postmortems/2026-03-20-payment-service-crashloop.md
+  Created: docs/runbooks/payment-service-secret-rotation.md
+  Created: docs/runbooks/payment-service-stripe-webhook-failure.md
+  Updated: docs/incidents/index.md
+
+Phase 4: IMPROVE
+  SLO impact: Consumed 100% of weekly error budget. Feature freeze recommended.
+  Action items:
+    1. [P0] Add Vault agent sidecar with auto-restart on secret change (owner: @platform)
+    2. [P0] Replace panic with error return in webhook handler (owner: @payments)
+    3. [P1] Add synthetic Stripe webhook test to canary suite (owner: @payments)
+    4. [P2] Create secret rotation runbook for all services (owner: @sre)
+```
+
+## Gates
+
+- **No postmortem without a root cause statement.** A postmortem that says "cause unknown" is incomplete. If the root cause cannot be determined, the postmortem must document what was investigated, what was ruled out, and what additional data is needed. Do not close the investigation.
+- **No action items without owners.** Every action item must have an assigned owner and a due date. Unowned action items are never completed. If no owner can be identified, escalate to the team lead.
+- **No severity downgrade without justification.** If a severity is reclassified during investigation, the reason must be documented in the postmortem timeline. Severity downgrades without evidence indicate pressure to minimize, not genuine reassessment.
+- **No skipping the improvement phase.** Documentation without follow-through produces shelf-ware. The improvement phase must produce at least one concrete, actionable item per contributing factor identified.
+
+## Escalation
+
+- **When root cause cannot be determined from code alone:** The incident may require production logs, metrics, or traces that are not available in the codebase. Report: "Root cause analysis requires access to [specific observability data]. Recommend reviewing [Datadog/Grafana/CloudWatch] dashboards for the incident window."
+- **When the incident reveals a systemic architecture issue:** A single postmortem action item is insufficient. Report: "This incident pattern indicates a systemic issue with [description]. Recommend a dedicated architecture review using harness-architecture-advisor."
+- **When SLO definitions do not exist:** Error budget calculation is impossible without SLOs. Report: "No SLO definitions found. Recommend establishing baseline SLOs before the next incident review. See the SLO starter template in docs/runbooks/slo-template.yaml."
+- **When multiple teams are involved in the blast radius:** A single postmortem owner may not have visibility into all contributing factors. Report: "This incident spans [N] services owned by [teams]. Recommend a joint postmortem review with representatives from each team."

package/dist/agents/skills/cursor/harness-incident-response/skill.yaml

@@ -0,0 +1,78 @@
+name: harness-incident-response
+version: "1.0.0"
+description: Runbook generation, postmortem analysis, and SLO/SLA tracking
+cognitive_mode: diagnostic-investigator
+triggers:
+  - manual
+  - on_bug_fix
+platforms:
+  - claude-code
+  - gemini-cli
+tools:
+  - Bash
+  - Read
+  - Write
+  - Edit
+  - Glob
+  - Grep
+  - emit_interaction
+cli:
+  command: harness skill run harness-incident-response
+  args:
+    - name: path
+      description: Project root path
+      required: false
+    - name: mode
+      description: "Operating mode: runbook, postmortem, or slo. Auto-detected when omitted."
+      required: false
+    - name: severity
+      description: "Incident severity: sev1, sev2, sev3, sev4. Defaults to sev3."
+      required: false
+mcp:
+  tool: run_skill
+  input:
+    skill: harness-incident-response
+    path: string
+type: rigid
+tier: 3
+internal: false
+keywords:
+  - incident
+  - runbook
+  - postmortem
+  - SLO
+  - SLA
+  - SLI
+  - on-call
+  - alert
+  - severity
+  - MTTR
+  - MTTD
+  - error budget
+  - incident management
+  - PagerDuty
+  - OpsGenie
+stack_signals:
+  - "runbooks/"
+  - "docs/runbooks/"
+  - "docs/incidents/"
+  - "docs/postmortems/"
+  - "slo.yaml"
+  - ".pagerduty*"
+phases:
+  - name: assess
+    description: Determine incident scope, severity, and affected services from available evidence
+    required: true
+  - name: investigate
+    description: Trace root cause through logs, metrics, dependencies, and recent changes
+    required: true
+  - name: document
+    description: Generate runbooks, postmortem reports, and timeline reconstructions
+    required: true
+  - name: improve
+    description: Propose SLO adjustments, alerting improvements, and preventive action items
+    required: true
+state:
+  persistent: false
+  files: []
+depends_on: []