Structured Learnings Enhancement

[chadjw]

Optional root_cause and tried_and_failed fields for learning entries. Semantic overlap check (5-dimension scoring) before creating new entries — prevents near-duplicate learnings with different wording. Active staleness detection auditing learnings against current code state. Learnings-researcher as always-on reviewer in code review pipeline. Inspired by Compound Engineering Plugin. [ACE-C5/C6]
Spec: .harness/architecture/awesome-claude-code-integration/ADR-001.md

[chadjw]

Harness Analysis: structured-learnings-21c7a090

Risk: low (80% confidence)
Route: local
Analyzed: 2026-04-16T20:36:09.265Z

• Structural complexity: 0.01 (12 files, 0 services, 0 modules affected)
• Semantic complexity: 0.51 (3 unknowns, 2 ambiguities, 2 risk signals)
• Historical complexity: 0.00 (from past execution outcomes)
• Overall: 0.18 → risk level "low", recommended route "local"

Full Analysis Data

{
  "_harness_analysis": true,
  "_version": 1,
  "issueId": "structured-learnings-21c7a090",
  "identifier": "structured-learnings-21c7a090",
  "spec": {
    "id": "structured-learnings-21c7a090",
    "title": "Structured Learnings Enhancement",
    "intent": "To enrich the structured learnings system by adding optional root cause and tried-and-failed fields, implementing a semantic overlap check before entry creation, and integrating active staleness detection into the code review pipeline.",
    "summary": "Enhance the Structured Learnings module with fields for root causes and failed attempts. A new semantic overlap check must be introduced (using a 5-dimension scoring model) to prevent near-duplicate entries. Furthermore, active staleness detection should be added, with the learnings researcher serving as a reviewer in the code review pipeline. This feature draws inspiration from the Compound Engineering Plugin.",
    "affectedSystems": [
      {
        "name": "StructuredLearningsModule",
        "graphNodeId": "module:packages/cli/src/commands/learnings",
        "confidence": 0.7,
        "transitiveDeps": [
          "file:packages/cli/src/commands/learnings/index.ts",
          "file:packages/cli/src/commands/learnings/prune.ts"
        ],
        "testCoverage": 0,
        "owner": null
      },
      {
        "name": "CodeReviewPipeline",
        "graphNodeId": "module:packages/core/src/feedback/review",
        "confidence": 0.7,
        "transitiveDeps": [
          "file:packages/core/src/feedback/review/checklist.ts",
          "file:packages/core/src/feedback/review/diff-analyzer.ts",
          "file:packages/core/src/feedback/review/peer-review.ts",
          "file:packages/core/src/feedback/review/self-review.ts"
        ],
        "testCoverage": 0,
        "owner": null
      }
    ],
    "functionalRequirements": [
      "Allow optional fields for `root_cause` and `tried_and_failed` in learning entries.",
      "Implement a semantic overlap checker using 5-dimension scoring before creating new learnings to prevent near-duplicates.",
      "Integrate active staleness detection mechanisms to audit learning entries against the current code state.",
      "Assign the Learnings Researcher as an always-on reviewer within the code review pipeline."
    ],
    "nonFunctionalRequirements": [],
    "apiChanges": [],
    "dbChanges": [],
    "integrationPoints": [
      "Compound Engineering Plugin (as inspiration/model)"
    ],
    "assumptions": [],
    "unknowns": [
      "The specific definition and scoring weights for the 5-dimension semantic overlap check.",
      "How 'current code state' is defined and accessed for staleness detection (e.g., branch, commit hash, deployed version).",
      "The technical implementation details of the 'always-on reviewer' role and its workflow integration into the pipeline."
    ],
    "ambiguities": [
      "The exact lifecycle of a learning entry once it passes the initial checks.",
      "Whether 'staleness detection' suggests requiring updates to the learning itself or just flagging it as potentially outdated."
    ],
    "riskSignals": [
      "High technical risk associated with reliably implementing the 5-dimension semantic scoring and accurately defining 'current code state'.",
      "Potential disruption to existing workflows if the review pipeline dependency on this new check is not carefully managed."
    ],
    "initialComplexityHints": {
      "textualComplexity": 0.8,
      "structuralComplexity": 1
    }
  },
  "score": {
    "overall": 0.1839048040565705,
    "confidence": 0.8,
    "riskLevel": "low",
    "blastRadius": {
      "services": 0,
      "modules": 0,
      "filesEstimated": 12,
      "testFilesAffected": 0
    },
    "dimensions": {
      "structural": 0.01215,
      "semantic": 0.5080851544473444,
      "historical": 0
    },
    "reasoning": [
      "Structural complexity: 0.01 (12 files, 0 services, 0 modules affected)",
      "Semantic complexity: 0.51 (3 unknowns, 2 ambiguities, 2 risk signals)",
      "Historical complexity: 0.00 (from past execution outcomes)",
      "Overall: 0.18 → risk level \"low\", recommended route \"local\""
    ],
    "recommendedRoute": "local"
  },
  "simulation": {
    "simulatedPlan": [
      "Update `StructuredLearningsModule` schema to include optional fields `root_cause` and `tried_and_failed`. This modifies the data models accessed by commands in `packages/cli/src/commands/learnings`.",
      "Develop and integrate the 5-dimension semantic overlap checker. This function must compare new entries against existing learnings using the undefined scoring model and trigger a block/flag if duplication exceeds a threshold.",
      "Implement active staleness detection logic. This requires defining and querying the 'current code state' (e.g., base branch/commit) against the learning entry.",
      "Integrate the staleness detection into the submission workflow of `StructuredLearningsModule`.",
      "Modify `CodeReviewPipeline` to introduce a new mandatory reviewer role (Learnings Researcher) whose approval is contingent on the staleness check result.",
      "Tie the lifecycle management into the pipeline, ensuring entries are flagged as 'Stale' or 'Current' based on audit checks."
    ],
    "predictedFailures": [
      "CRITICAL: The implementation of the 5-dimension scoring model is impossible without specific weights and comparison logic, leading to arbitrary uniqueness enforcement or accidental acceptance of near-duplicates. (High Risk)",
      "Definition mismatch between 'current code state' and the system's source control reality, leading to transient bugs where a learning is flagged as stale immediately after its creation.",
      "The reviewer role implementation in `CodeReviewPipeline` might introduce blocking deadlocks if the Researcher has no defined action (e.g., 'Accept Staleness').",
      "API regression risk: Modifying the input validation layer of `StructuredLearningsModule` might unintentionally break existing CLI consumers that do not pass the new optional fields, causing unexpected data formatting errors."
    ],
    "riskHotspots": [
      "review (high fan-out)",
      "peer-review.ts (high fan-out)",
      "The coupling between the initial entry creation and the rigorous staleness check introduces latency and a high probability of immediate functional blockage.",
      "The reliance on external, undefined domain knowledge (the 5-dimension scoring weights) means the agent cannot complete the task accurately, forcing speculative implementation.",
      "The tight coupling of `Learnings Researcher` approval into the core `CodeReviewPipeline` means failure here impacts the entire feedback loop, requiring robust error handling for timing out or reviewer absence."
    ],
    "missingSteps": [
      "The spec does not define the acceptable thresholds for semantic overlap or staleness, meaning the agent must guess constants which is prone to error.",
      "The specific API contract/interface for querying the 'current code state' must be established and secured before attempting staleness checks.",
      "A rollback or grace period mechanism needs to be designed for entries flagged as Stale, rather than simply being audited against a perfect current state."
    ],
    "testGaps": [
      "StructuredLearningsModule: no test coverage detected",
      "CodeReviewPipeline: no test coverage detected",
      "Blast radius covers 12 files but no test files are affected",
      "Lack of integration tests between the new semantic checker and the `StructuredLearningsModule` submission endpoint.",
      "Unit tests for the 5-dimension scoring function (if weights are eventually provided) against predefined edge cases.",
      "End-to-end tests simulating the full lifecycle: Entry Creation -> Semantic Check Pass -> Code Review Submission -> Staleness Audit -> Researcher Approval. This workflow is complex and currently untestable due to unknowns.",
      "Regression tests ensuring the introduction of new fields (`root_cause`, `tried_and_failed`) does not break existing, successful learning entries."
    ],
    "executionConfidence": 0.012414279391514405,
    "recommendedChanges": [
      "StructuredLearningsModule: affected code has no test coverage in cascade path",
      "CodeReviewPipeline: affected code has no test coverage in cascade path",
      "Force a definition phase for the 5-dimension scoring weights and the 'current code state' API interface before coding begins.",
      "Simplify the initial integration by making staleness detection a *post-submission audit* rather than a blocking pre-entry check, mitigating immediate pipeline friction.",
      "Establish clear acceptance criteria for the 'Learnings Researcher' action (e.g., Approve, Reject, Defer) to prevent workflow deadlocks."
    ],
    "abort": true,
    "tier": "full-simulation"
  },
  "analyzedAt": "2026-04-16T20:36:09.265Z",
  "externalId": "github:Intense-Visions/harness-engineering#112"
}

[chadjw]

Orchestrator Claimed orchestrator-ad1c7656

Field	Value
Time	2026-04-19 22:08:56 UTC
Orchestrator	orchestrator-ad1c7656
Event	Dispatching agent for autonomous execution

[chadjw]

Orchestrator Completed orchestrator-ad1c7656

Field	Value
Time	2026-04-19 22:15:00 UTC
Orchestrator	orchestrator-ad1c7656
Event	Agent finished successfully