orchestr8 2.4.0 → 2.6.0

package/.blueprint/features/feature_pipeline-insights/FEATURE_SPEC.md

@@ -0,0 +1,288 @@
+# Feature Specification — Pipeline Insights
+
+## 1. Feature Intent
+
+**Why this feature exists.**
+
+- **Problem being addressed:** The pipeline-history feature captures execution data but provides only basic statistics. Users cannot identify optimization opportunities—such as bottleneck stages, failure patterns, or performance trends—without manual analysis of the raw history data.
+- **User need:** Developers want actionable recommendations to improve pipeline efficiency. They need to understand which stages are slowest, why failures occur, and whether the pipeline is improving or degrading over time.
+- **System purpose alignment:** Per SYSTEM_SPEC.md:Section 8 (Cross-Cutting Concerns:Observability), the system aims for observability via queue status and agent summaries. Per SYSTEM_SPEC.md:Section 2 (Business & Domain Context), orchestr8 seeks to provide "structured processes to guide AI-generated code." This feature extends observability into actionable intelligence, enabling users to optimize their development workflow.
+
+> This feature builds upon the existing pipeline-history feature (`.blueprint/features/feature_pipeline-history/FEATURE_SPEC.md`) without modifying history recording. It is a read-only analysis layer.
+
+---
+
+## 2. Scope
+
+### In Scope
+
+- New CLI command `orchestr8 insights` that analyzes `.claude/pipeline-history.json`
+- Bottleneck detection: Identify which stage consistently takes longest
+- Failure pattern analysis: Determine which stages fail most and correlate with feature characteristics
+- Anomaly detection: Flag runs that deviate significantly from average durations
+- Trend analysis: Track whether pipeline performance is improving or degrading over time
+- Agent performance comparison: Compare stage durations and success rates across agents
+- Flag support for filtering analysis types (`--bottlenecks`, `--failures`, `--json`)
+- Human-readable recommendations based on detected patterns
+
+### Out of Scope
+
+- Modifying pipeline-history recording logic (that feature is separate)
+- Machine learning or complex statistical models (simple heuristics only)
+- Automatic remediation or pipeline configuration changes
+- Integration with external analytics platforms
+- Predictive modelling of future pipeline performance
+- Feature-type classification (assumes slugs are opaque identifiers)
+
+---
+
+## 3. Actors Involved
+
+### Human User
+
+- **Can do:** Invoke `orchestr8 insights` to view optimization recommendations; filter by analysis type; export as JSON for programmatic use
+- **Cannot do:** Modify the analysis thresholds or algorithms; act on recommendations automatically
+
+### Insights Analyzer (internal component)
+
+- **Can do:** Read history file; compute statistics; generate recommendations; output formatted reports
+- **Cannot do:** Write to history file; modify pipeline configuration; alter agent behaviour
+
+---
+
+## 4. Behaviour Overview
+
+### Happy-path behaviour
+
+1. User runs `orchestr8 insights` after accumulating several pipeline runs
+2. System reads `.claude/pipeline-history.json` and validates data sufficiency
+3. System performs analysis across four dimensions: bottlenecks, failures, anomalies, trends
+4. System generates human-readable report with recommendations
+5. User reviews recommendations and decides which to act upon
+
+### Key alternatives or branches
+
+- **Insufficient data:** If fewer than 3 runs exist, display message: "Insufficient data for insights. Complete at least 3 pipeline runs."
+- **No failures:** If all runs succeeded, omit failure analysis section; note "No failures recorded"
+- **Filtered analysis:** If `--bottlenecks` or `--failures` flag provided, display only that section
+- **JSON output:** If `--json` flag provided, output structured JSON instead of formatted text
+- **Corrupted history:** If history file is corrupted, display warning and exit gracefully
+
+### User-visible outcomes
+
+- Identification of the slowest pipeline stage with percentage of total time
+- List of stages with high failure rates and potential contributing factors
+- Flagged anomalous runs that deviated significantly from norms
+- Trend indicators showing improvement or degradation over recent runs
+- Actionable recommendations for each identified issue
+
+---
+
+## 5. State & Lifecycle Interactions
+
+### States entered
+
+- None. This feature is stateless and read-only.
+
+### States modified
+
+- None. This feature does not modify any system state.
+
+### This feature is:
+
+- **Not state-creating:** Does not persist analysis results
+- **Not state-transitioning:** Does not alter pipeline flow
+- **Not state-constraining:** Does not block any operations
+
+This is a pure read-only analysis feature that operates on existing history data.
+
+---
+
+## 6. Rules & Decision Logic
+
+### Rule: Bottleneck Detection
+
+- **Description:** Identify the stage that consumes the largest proportion of total pipeline time
+- **Inputs:** Stage durations from successful runs
+- **Outputs:** Stage name, average duration, percentage of total pipeline time
+- **Algorithm:** Calculate mean duration per stage; identify stage with highest mean; compute as percentage of sum
+- **Threshold:** Report as bottleneck if stage accounts for >35% of total pipeline time
+- **Deterministic:** Yes
+
+### Rule: Failure Pattern Analysis
+
+- **Description:** Identify stages with disproportionate failure rates and correlate with feature characteristics
+- **Inputs:** All history entries with status `failed`; feature slugs
+- **Outputs:** Failure rate per stage; most common failure stage; correlation hints
+- **Algorithm:** Count failures by stage; compute failure rate as failures/total runs for that stage; identify features with repeated failures
+- **Threshold:** Report as concerning if failure rate >15%
+- **Deterministic:** Yes
+
+### Rule: Anomaly Detection
+
+- **Description:** Flag individual runs where stage duration deviates significantly from average
+- **Inputs:** Stage durations from all runs; calculated means and standard deviations
+- **Outputs:** List of anomalous runs with stage, actual duration, expected duration
+- **Algorithm:** Calculate mean and standard deviation per stage; flag if duration > mean + 2*stddev
+- **Threshold:** 2 standard deviations above mean
+- **Scope:** Last 10 runs only (to limit output)
+- **Deterministic:** Yes
+
+### Rule: Trend Analysis
+
+- **Description:** Determine if pipeline performance is improving or degrading over time
+- **Inputs:** All history entries, sorted chronologically
+- **Outputs:** Success rate trend (improving/stable/degrading); duration trend (improving/stable/degrading)
+- **Algorithm:** Compare metrics from first half vs second half of history; compute percentage change
+- **Thresholds:** Improving if >10% better; degrading if >10% worse; stable otherwise
+- **Minimum data:** Requires at least 6 runs to compute trends
+- **Deterministic:** Yes
+
+### Rule: Agent Performance Comparison
+
+- **Description:** Compare duration and success metrics across agent stages
+- **Inputs:** All history entries with stage data
+- **Outputs:** Ranked list of stages by average duration; success rate per stage
+- **Algorithm:** Aggregate durations and success/failure counts per stage; rank by mean duration
+- **Deterministic:** Yes
+
+### Rule: Recommendation Generation
+
+- **Description:** Generate actionable recommendations based on detected patterns
+- **Inputs:** Analysis results from all rules above
+- **Outputs:** Human-readable recommendation strings
+- **Logic:**
+  - If bottleneck stage is >40% of time → "Consider simplifying {stage} requirements or splitting features"
+  - If failure rate >20% on a stage → "Review {stage} agent configuration or specification clarity"
+  - If anomalies detected → "Investigate flagged runs for unusual feature complexity"
+  - If degrading trend → "Review recent changes to agent specifications or system spec"
+- **Deterministic:** Yes (same inputs produce same recommendations)
+
+---
+
+## 7. Dependencies
+
+### System components
+
+- `src/history.js` — Must expose `readHistoryFile()` function; currently exports this
+- `bin/cli.js` — Must register new `insights` command
+- `.claude/pipeline-history.json` — Must exist with entries from pipeline-history feature
+
+### Upstream features
+
+- **pipeline-history** (`.blueprint/features/feature_pipeline-history/`) — This feature depends entirely on history data recorded by pipeline-history. The history entry schema (slug, status, stages, timestamps, durations) must be stable.
+
+### External systems
+
+- None
+
+### Operational dependencies
+
+- File system read access to `.claude/pipeline-history.json`
+
+---
+
+## 8. Non-Functional Considerations
+
+### Performance sensitivity
+
+- Analysis is computed on-demand from full history file
+- ASSUMPTION: History files contain <500 entries; O(n) algorithms acceptable
+- No caching required; each invocation recomputes from scratch
+
+### Audit/logging needs
+
+- None. This feature is read-only and does not produce persistent outputs.
+
+### Error tolerance
+
+- If history file is missing, display "No history found. Run some pipelines first."
+- If history file is corrupted, display warning and exit gracefully
+- If insufficient data for specific analysis, skip that section with explanation
+
+### Security implications
+
+- Feature slugs may reveal project information; output to terminal only
+- JSON output should not include sensitive data beyond what is already in history file
+
+---
+
+## 9. Assumptions & Open Questions
+
+### Assumptions
+
+- ASSUMPTION: The history entry schema from pipeline-history is stable: `{ slug, status, stages, completedAt, totalDurationMs }`
+- ASSUMPTION: Stage names are fixed: `alex`, `cass`, `nigel`, `codey-plan`, `codey-implement`
+- ASSUMPTION: 2 standard deviations is an appropriate anomaly threshold for this domain
+- ASSUMPTION: 6 runs provides sufficient data for meaningful trend analysis
+- ASSUMPTION: Users will act on recommendations manually; no automation required
+
+### Open Questions
+
+- Should anomaly detection consider stage-specific thresholds rather than uniform 2-stddev?
+- Should trend analysis use a sliding window rather than first-half/second-half comparison?
+- Should there be a `--verbose` flag for more detailed analysis output?
+- Should the feature support analysis of a specific time range (e.g., last 30 days)?
+
+---
+
+## 10. Impact on System Specification
+
+### Alignment assessment
+
+This feature **reinforces existing system assumptions**:
+
+- Per SYSTEM_SPEC.md:Section 8 (Observability), the system already aims for visibility into pipeline execution
+- Per SYSTEM_SPEC.md:Section 5 (Core Domain Concepts), the queue and pipeline concepts are well-defined
+- This feature adds an intelligence layer without altering core pipeline behaviour
+
+### No contradictions identified
+
+The feature does not alter:
+
+- Agent roles or boundaries
+- Pipeline flow or stage order
+- Artifact structures or handoff mechanisms
+- History recording behaviour (defers entirely to pipeline-history feature)
+
+### Minor extension to system spec
+
+The following addition to SYSTEM_SPEC.md:Section 5 (Core Domain Concepts) may be warranted:
+
+> **Pipeline Insights** — An analysis layer that examines historical pipeline data to identify bottlenecks, failure patterns, anomalies, and trends. Provides recommendations for pipeline optimization without modifying pipeline behaviour.
+
+This is flagged as a **non-breaking extension** for consideration.
+
+---
+
+## 11. Handover to BA (Cass)
+
+### Story themes
+
+1. **Bottleneck analysis** — Identifying and reporting the slowest pipeline stages
+2. **Failure pattern analysis** — Analyzing failure frequency and generating recommendations
+3. **Anomaly detection** — Flagging runs that deviate significantly from averages
+4. **Trend analysis** — Computing and displaying performance trends over time
+5. **JSON output** — Supporting programmatic consumption of insights data
+
+### Expected story boundaries
+
+- Core insights engine (statistics computation) may be shared across stories
+- Each analysis type (bottlenecks, failures, anomalies, trends) is a candidate for separate story
+- JSON output support could be combined with any analysis story or kept separate
+- CLI command registration is infrastructure supporting all stories
+
+### Areas needing careful story framing
+
+- The threshold values (35% for bottleneck, 15% for failure rate, 2-stddev for anomaly) should be explicitly stated in acceptance criteria
+- The minimum data requirements (3 runs for basic insights, 6 runs for trends) need clear edge case handling
+- The recommendation text generation needs precise acceptance criteria for consistent output
+- Handling of ties in "most common failure stage" should be explicit
+
+---
+
+## 12. Change Log (Feature-Level)
+
+| Date       | Change                                | Reason                                    | Raised By |
+|------------|---------------------------------------|-------------------------------------------|-----------|
+| 2026-02-24 | Initial feature specification created | Extend pipeline-history with actionable insights | Alex |

package/.blueprint/features/feature_pipeline-insights/IMPLEMENTATION_PLAN.md

@@ -0,0 +1,65 @@
+# Implementation Plan — Pipeline Insights
+
+## Summary
+
+This feature adds a new `orchestr8 insights` CLI command that performs read-only analysis of pipeline history data. It computes bottleneck detection, failure patterns, anomaly detection, and trend analysis, outputting human-readable recommendations or JSON. The implementation creates a new `src/insights.js` module that reuses `readHistoryFile()` from the existing `src/history.js`.
+
+---
+
+## Files to Create/Modify
+
+| Path | Action | Purpose |
+|------|--------|---------|
+| `src/insights.js` | Create | Core analysis engine with all computation logic |
+| `bin/cli.js` | Modify | Register `insights` command and route flags |
+
+---
+
+## Implementation Steps
+
+1. **Create `src/insights.js` scaffold** - Export main `displayInsights(options)` function that reads history via `readHistoryFile()` and validates minimum data (3 runs).
+
+2. **Implement bottleneck analysis** - Calculate average duration per stage across successful runs; identify stage with highest mean; compute percentage of total; flag if >35%; generate recommendation if >40%.
+
+3. **Implement failure pattern analysis** - Count failures by stage; compute failure rate per stage; identify most common failure stage; list features with repeated failures; flag if rate >15%; generate recommendation if >20%.
+
+4. **Implement anomaly detection** - Calculate mean and stddev per stage from all runs; evaluate last 10 runs; flag any stage duration exceeding mean + 2*stddev; include slug, stage, actual, expected, deviation in output.
+
+5. **Implement trend analysis** - Require 6+ runs; split history into first and second halves; compare success rates and average durations; classify as improving/stable/degrading based on 10% threshold; show percentage change.
+
+6. **Implement output formatters** - Create `formatTextOutput(analysis)` for human-readable output and `formatJsonOutput(analysis)` for structured JSON; handle section filtering based on flags.
+
+7. **Handle edge cases** - Missing history file returns "No history found"; corrupted file shows warning; insufficient data (<3 runs) shows appropriate message; no failures omits failure section with "No failures recorded".
+
+8. **Register CLI command** - In `bin/cli.js`, import `displayInsights` from `src/insights.js`; add `insights` command with flag parsing for `--bottlenecks`, `--failures`, `--json`.
+
+9. **Run tests and verify** - Execute `node --test test/feature_pipeline-insights.test.js` after each file change; ensure all tests pass.
+
+10. **Final cleanup** - Verify output formatting matches AC requirements; ensure recommendations use exact wording from spec.
+
+---
+
+## Key Functions
+
+**In `src/insights.js`:**
+- `displayInsights(options)` - Main entry point; orchestrates analysis and output
+- `analyzeBottlenecks(history)` - Returns `{ stage, avgDurationMs, percentage, isBottleneck, recommendation }`
+- `analyzeFailures(history)` - Returns `{ failuresByStage, mostCommonStage, repeatedFeatures, recommendation }`
+- `detectAnomalies(history)` - Returns `{ anomalies: [{slug, stage, actual, expected, deviation}], recommendation }`
+- `analyzeTrends(history)` - Returns `{ successRate: {trend, change}, duration: {trend, change}, recommendation }`
+- `formatTextOutput(analysis, sections)` - Formats analysis as human-readable text
+- `formatJsonOutput(analysis, sections)` - Formats analysis as JSON object
+- `calculateMean(values)` - Helper: compute arithmetic mean
+- `calculateStdDev(values, mean)` - Helper: compute population standard deviation
+
+**In `bin/cli.js`:**
+- Extend `parseFlags()` to recognize `--bottlenecks`, `--failures`, `--json`
+- Add `insights` command entry in `commands` object
+
+---
+
+## Risks/Questions
+
+- **History schema assumption**: Implementation assumes `stages` is an object with `{name: {durationMs}}` structure per test-spec.md. If actual schema differs, adapter logic may be needed.
+- **Tie-breaking**: Per test-spec.md, ties in "most common failure stage" resolved by first occurrence. Implementation should use stable sort or maintain insertion order.
+- **Standard deviation formula**: Using population stddev (N divisor) per test-spec.md assumption, not sample stddev (N-1).

package/.blueprint/features/feature_pipeline-insights/story-anomaly-detection.md

@@ -0,0 +1,71 @@
+# Story — Anomaly Detection
+
+## User story
+
+As a developer, I want to identify pipeline runs where stage durations deviated significantly from normal so that I can investigate unusual behaviour and understand outliers.
+
+---
+
+## Context / scope
+
+- User has accumulated enough history data to establish baseline metrics
+- Analysis uses statistical deviation (mean + 2*stddev) to identify anomalies
+- Scope limited to last 10 runs to keep output manageable
+- This is a read-only analysis; no pipeline state is modified
+- Route: `orchestr8 insights` (anomaly section included by default)
+
+Per FEATURE_SPEC.md:Section 6 (Rule: Anomaly Detection):
+- Threshold: 2 standard deviations above mean
+- Scope: Last 10 runs only
+
+---
+
+## Acceptance criteria
+
+**AC-1 — Detect anomalous stage durations**
+- Given the history file contains at least 3 pipeline runs,
+- When the user runs `orchestr8 insights`,
+- Then the output includes an "Anomalies" section listing any runs where a stage duration exceeded mean + 2*stddev.
+
+**AC-2 — Display anomaly details**
+- Given an anomalous run is detected,
+- When the analysis completes,
+- Then the output shows: feature slug, stage name, actual duration, expected duration (mean), and deviation factor.
+
+**AC-3 — Limit scope to recent runs**
+- Given the history contains more than 10 runs,
+- When anomaly detection is performed,
+- Then only the most recent 10 runs are evaluated for anomalies.
+
+**AC-4 — Generate recommendation when anomalies found**
+- Given one or more anomalous runs are detected,
+- When the analysis completes,
+- Then the output includes the recommendation: "Investigate flagged runs for unusual feature complexity".
+
+**AC-5 — No anomalies detected**
+- Given all recent runs have stage durations within 2 standard deviations of the mean,
+- When the user runs `orchestr8 insights`,
+- Then the anomalies section displays: "No anomalies detected in recent runs."
+
+**AC-6 — Insufficient data for statistics**
+- Given the history file contains fewer than 3 runs,
+- When anomaly detection is attempted,
+- Then it is skipped with explanation: "Insufficient data for anomaly detection."
+
+---
+
+## Out of scope
+
+- Configurable standard deviation threshold
+- Stage-specific anomaly thresholds
+- Anomaly detection for failure counts (only duration-based)
+- Historical anomaly tracking beyond last 10 runs
+- Automatic investigation or drill-down into anomalous runs
+
+---
+
+## References
+
+- Feature spec: `.blueprint/features/feature_pipeline-insights/FEATURE_SPEC.md`
+- Upstream dependency: `.blueprint/features/feature_pipeline-history/FEATURE_SPEC.md`
+- System spec: `.blueprint/system_specification/SYSTEM_SPEC.md`

package/.blueprint/features/feature_pipeline-insights/story-bottleneck-analysis.md

@@ -0,0 +1,75 @@
+# Story — Bottleneck Analysis
+
+## User story
+
+As a developer, I want to identify which pipeline stage consistently takes the longest so that I can focus optimization efforts where they will have the greatest impact.
+
+---
+
+## Context / scope
+
+- User has executed multiple pipeline runs via `/implement-feature`
+- History data exists in `.claude/pipeline-history.json`
+- This is a read-only analysis; no pipeline state is modified
+- Route: `orchestr8 insights` or `orchestr8 insights --bottlenecks`
+
+Per FEATURE_SPEC.md:Section 6 (Rule: Bottleneck Detection):
+- Bottleneck threshold: >35% of total pipeline time
+- Recommendation threshold: >40% of total pipeline time
+
+---
+
+## Acceptance criteria
+
+**AC-1 — Display bottleneck stage**
+- Given the history file contains at least 3 successful pipeline runs,
+- When the user runs `orchestr8 insights`,
+- Then the output includes a "Bottlenecks" section identifying the stage with the highest average duration.
+
+**AC-2 — Show percentage of total time**
+- Given a bottleneck stage is identified,
+- When the analysis completes,
+- Then the output displays the stage name, average duration in milliseconds, and percentage of total pipeline time.
+
+**AC-3 — Bottleneck threshold reporting**
+- Given a stage accounts for more than 35% of total pipeline time,
+- When the analysis completes,
+- Then that stage is flagged as a bottleneck in the output.
+
+**AC-4 — Generate recommendation for severe bottleneck**
+- Given a stage accounts for more than 40% of total pipeline time,
+- When the analysis completes,
+- Then the output includes the recommendation: "Consider simplifying {stage} requirements or splitting features".
+
+**AC-5 — Filter to bottlenecks only**
+- Given the user runs `orchestr8 insights --bottlenecks`,
+- When the analysis completes,
+- Then only the bottleneck analysis section is displayed (other analysis types are omitted).
+
+**AC-6 — Insufficient data handling**
+- Given the history file contains fewer than 3 runs,
+- When the user runs `orchestr8 insights`,
+- Then the output displays: "Insufficient data for insights. Complete at least 3 pipeline runs."
+
+**AC-7 — Missing history file handling**
+- Given no history file exists at `.claude/pipeline-history.json`,
+- When the user runs `orchestr8 insights`,
+- Then the output displays: "No history found. Run some pipelines first."
+
+---
+
+## Out of scope
+
+- Modifying the history file or pipeline configuration
+- Customizing the 35%/40% threshold values
+- Providing automated remediation
+- Stage-specific threshold configuration
+- Analysis of partial/in-progress runs
+
+---
+
+## References
+
+- Feature spec: `.blueprint/features/feature_pipeline-insights/FEATURE_SPEC.md`
+- Upstream dependency: `.blueprint/features/feature_pipeline-history/FEATURE_SPEC.md`
+- System spec: `.blueprint/system_specification/SYSTEM_SPEC.md`

package/.blueprint/features/feature_pipeline-insights/story-failure-patterns.md

@@ -0,0 +1,75 @@
+# Story — Failure Pattern Analysis
+
+## User story
+
+As a developer, I want to analyze which pipeline stages fail most frequently so that I can identify systemic issues and improve pipeline reliability.
+
+---
+
+## Context / scope
+
+- User has executed multiple pipeline runs, some of which have failed
+- History data includes entries with `status: "failed"` and associated stage information
+- This is a read-only analysis; no pipeline state is modified
+- Route: `orchestr8 insights` or `orchestr8 insights --failures`
+
+Per FEATURE_SPEC.md:Section 6 (Rule: Failure Pattern Analysis):
+- Failure rate threshold: >15% is reported as concerning
+- Recommendation threshold: >20% triggers specific recommendation
+
+---
+
+## Acceptance criteria
+
+**AC-1 — Display failure rates per stage**
+- Given the history file contains at least 3 pipeline runs with at least one failure,
+- When the user runs `orchestr8 insights`,
+- Then the output includes a "Failure Patterns" section showing failure rate for each stage that has experienced failures.
+
+**AC-2 — Identify most common failure stage**
+- Given failures exist in the history,
+- When the analysis completes,
+- Then the output identifies the stage with the highest failure count as the "most common failure stage".
+
+**AC-3 — Flag concerning failure rates**
+- Given a stage has a failure rate greater than 15%,
+- When the analysis completes,
+- Then that stage is flagged as having a concerning failure rate.
+
+**AC-4 — Generate recommendation for high failure rate**
+- Given a stage has a failure rate greater than 20%,
+- When the analysis completes,
+- Then the output includes the recommendation: "Review {stage} agent configuration or specification clarity".
+
+**AC-5 — Identify features with repeated failures**
+- Given the same feature slug has failed multiple times,
+- When the analysis completes,
+- Then those features are listed as correlation hints (e.g., "Feature 'complex-auth' has failed 3 times").
+
+**AC-6 — Filter to failures only**
+- Given the user runs `orchestr8 insights --failures`,
+- When the analysis completes,
+- Then only the failure pattern analysis section is displayed (other analysis types are omitted).
+
+**AC-7 — No failures recorded**
+- Given all pipeline runs in history have status "completed" (no failures),
+- When the user runs `orchestr8 insights`,
+- Then the failure analysis section displays: "No failures recorded" and is omitted from recommendations.
+
+---
+
+## Out of scope
+
+- Automatic correlation with feature complexity metrics
+- Root cause analysis beyond stage identification
+- Failure notification or alerting
+- Retry or remediation automation
+- Classification of failure types (timeout vs error vs abort)
+
+---
+
+## References
+
+- Feature spec: `.blueprint/features/feature_pipeline-insights/FEATURE_SPEC.md`
+- Upstream dependency: `.blueprint/features/feature_pipeline-history/FEATURE_SPEC.md`
+- System spec: `.blueprint/system_specification/SYSTEM_SPEC.md`

package/.blueprint/features/feature_pipeline-insights/story-json-output.md

@@ -0,0 +1,75 @@
+# Story — JSON Output
+
+## User story
+
+As a developer, I want to export pipeline insights as structured JSON so that I can integrate the analysis with other tools or process the data programmatically.
+
+---
+
+## Context / scope
+
+- User wants machine-readable output instead of human-readable text
+- JSON output contains all the same analysis data as text output
+- Enables integration with CI/CD pipelines, dashboards, or custom tooling
+- This is a read-only analysis; no pipeline state is modified
+- Route: `orchestr8 insights --json`
+
+Per FEATURE_SPEC.md:Section 4 (Key alternatives or branches):
+- `--json` flag produces structured JSON instead of formatted text
+
+---
+
+## Acceptance criteria
+
+**AC-1 — Output JSON when flag provided**
+- Given the history file contains valid pipeline data,
+- When the user runs `orchestr8 insights --json`,
+- Then the output is valid JSON (parseable by `JSON.parse()`).
+
+**AC-2 — Include bottleneck data in JSON**
+- Given bottleneck analysis completes successfully,
+- When `--json` flag is provided,
+- Then the JSON output includes a `bottlenecks` object with: `stage`, `averageDurationMs`, `percentageOfTotal`, `isBottleneck`, `recommendation` (if applicable).
+
+**AC-3 — Include failure data in JSON**
+- Given failure analysis completes successfully,
+- When `--json` flag is provided,
+- Then the JSON output includes a `failures` object with: `failuresByStage` (array), `mostCommonFailureStage`, `featuresWithRepeatedFailures` (array), `recommendation` (if applicable).
+
+**AC-4 — Include anomaly data in JSON**
+- Given anomaly detection completes successfully,
+- When `--json` flag is provided,
+- Then the JSON output includes an `anomalies` object with: `detected` (array of anomalous runs), `recommendation` (if applicable).
+
+**AC-5 — Include trend data in JSON**
+- Given trend analysis completes successfully,
+- When `--json` flag is provided,
+- Then the JSON output includes a `trends` object with: `successRate` (trend + percentage), `duration` (trend + percentage), `recommendation` (if applicable).
+
+**AC-6 — Combine JSON with filter flags**
+- Given the user runs `orchestr8 insights --json --bottlenecks`,
+- When the analysis completes,
+- Then the JSON output includes only the `bottlenecks` section (other analysis types are omitted).
+
+**AC-7 — Handle insufficient data in JSON**
+- Given there is insufficient data for analysis,
+- When `--json` flag is provided,
+- Then the JSON output includes an `error` field with the appropriate message (e.g., `{"error": "Insufficient data for insights. Complete at least 3 pipeline runs."}`).
+
+---
+
+## Out of scope
+
+- Exporting JSON to a file (output to stdout only)
+- JSON schema validation or versioning
+- Compressed or minified JSON output options
+- Integration with specific external platforms
+- Historical JSON output comparison
+
+---
+
+## References
+
+- Feature spec: `.blueprint/features/feature_pipeline-insights/FEATURE_SPEC.md`
+- Upstream dependency: `.blueprint/features/feature_pipeline-history/FEATURE_SPEC.md`
+- System spec: `.blueprint/system_specification/SYSTEM_SPEC.md`