aiwg
Version:
Cognitive architecture for AI-augmented software development with structured memory, ensemble validation, and closed-loop correction. FAIR-aligned artifacts, 84% cost reduction via human-in-the-loop, standards adopted by 100+ organizations.
321 lines (292 loc) • 11.2 kB
YAML
# Debug Provenance Schema
# Based on REF-058 R-LAM Provenance-Assisted LLM
# Issue: #246
$schema: "https://json-schema.org/draft/2020-12/schema"
$id: "https://aiwg.io/schemas/debug-provenance/v1"
title: "Debug Provenance Schema"
description: |
Provenance-assisted debugging workflow that reduces debug time by 35-50%
through instant access to artifact derivation chains per REF-058.
type: object
required:
- version
- debug_contexts
- provenance_queries
properties:
version:
type: string
pattern: "^\\d+\\.\\d+\\.\\d+$"
default: "1.0.0"
debug_contexts:
$ref: "#/$defs/DebugContexts"
provenance_queries:
$ref: "#/$defs/ProvenanceQueries"
$defs:
DebugContexts:
type: object
description: "Context building for debugging scenarios"
properties:
enabled:
type: boolean
default: true
research_backing:
type: object
properties:
source: { type: string, default: "REF-058" }
finding: { type: string, default: "Provenance tracking reduces debugging time by 35-50%" }
mechanism: { type: string, default: "Instant access to artifact derivation chains" }
context_types:
type: object
properties:
test_failure:
type: object
properties:
description: { type: string, default: "Analyze test failure with provenance chain" }
workflow:
type: array
items: { type: string }
default:
- "Parse test failure output"
- "Identify failing test file and line"
- "Trace backward to source implementation"
- "Trace further to requirement specification"
- "Identify mismatches between requirement and implementation"
- "Suggest fix based on provenance analysis"
context_schema:
type: object
properties:
test_file: { type: string, description: "Path to failing test" }
test_line: { type: integer, description: "Line number of failure" }
source_file: { type: string, description: "Implementation file" }
requirement: { type: string, description: "Related requirement artifact" }
nfr_constraint: { type: string, description: "Relevant NFR constraint" }
mismatch: { type: string, description: "Identified mismatch" }
suggested_fix:
type: object
properties:
file: { type: string }
line: { type: integer }
change: { type: string }
reason: { type: string }
architecture_context:
type: object
properties:
description: { type: string, default: "Provide architectural context for code" }
workflow:
type: array
items: { type: string }
default:
- "Identify file being examined"
- "Find related Architecture Decision Records (ADRs)"
- "Extract relevant NFRs"
- "Summarize design rationale"
- "Show recent change history"
context_schema:
type: object
properties:
artifact: { type: string }
adrs:
type: array
items:
type: object
properties:
id: { type: string }
title: { type: string }
rationale: { type: string }
date: { type: string }
nfrs:
type: array
items:
type: object
properties:
category: { type: string }
constraint: { type: string }
change_history:
type: array
items:
type: object
properties:
date: { type: string }
agent: { type: string }
change: { type: string }
reason: { type: string }
impact_analysis:
type: object
properties:
description: { type: string, default: "Analyze impact of changing an artifact" }
workflow:
type: array
items: { type: string }
default:
- "Load artifact being considered for change"
- "Trace forward to find all dependents"
- "Categorize by type (code, test, doc)"
- "Identify affected agents"
- "Generate impact summary"
context_schema:
type: object
properties:
artifact: { type: string }
direct_dependencies:
type: array
items:
type: object
properties:
path: { type: string }
type: { type: string, enum: [code, test, doc, requirement] }
relationship: { type: string }
transitive_dependencies:
type: array
items:
type: object
properties:
path: { type: string }
type: { type: string }
depth: { type: integer }
affected_agents:
type: array
items:
type: object
properties:
agent: { type: string }
owns: { type: string }
recommendation: { type: string }
time_savings:
type: object
properties:
target: { type: string, default: "35-50% reduction in debugging time" }
metrics:
type: array
items: { type: string }
default:
- "Average time to identify bug root cause (before/after)"
- "Average time to find relevant requirements (before/after)"
- "Number of incorrect fixes avoided via provenance"
ProvenanceQueries:
type: object
description: "Provenance query patterns for debugging"
properties:
backward_trace:
type: object
properties:
description: { type: string, default: "Find origin artifacts for given target" }
query_types:
type: array
items: { type: string }
default:
- "What requirement does this code implement?"
- "What ADR explains this design choice?"
- "What NFR constrains this behavior?"
- "When was this code created and by whom?"
forward_trace:
type: object
properties:
description: { type: string, default: "Find dependent artifacts for given source" }
query_types:
type: array
items: { type: string }
default:
- "What code implements this requirement?"
- "What tests cover this implementation?"
- "What documentation describes this feature?"
- "Who would be affected by changing this?"
mismatch_detection:
type: object
properties:
description: { type: string, default: "Find inconsistencies in derivation chain" }
checks:
type: array
items: { type: string }
default:
- "Requirement specifies X, but implementation does Y"
- "NFR constraint violated by implementation"
- "Test expects behavior inconsistent with requirement"
- "Documentation out of sync with implementation"
# CLI commands
cli_commands:
debug:
command: "aiwg debug <path> [line]"
description: "Debug artifact with provenance context"
options:
- name: "--line"
short: "-l"
description: "Specific line number for context"
- name: "--impact"
short: "-i"
description: "Show impact analysis instead of debug context"
- name: "--format"
short: "-f"
description: "Output format (text, json, mermaid)"
default: "text"
# Agent protocol
agent_protocol:
build_debug_context:
description: "Build debugging context for artifact"
steps:
- parse_error_or_artifact_path
- if_test_failure:
- extract_test_file_and_line
- trace_backward_to_source
- trace_backward_to_requirement
- trace_to_nfr_constraints
- identify_mismatches
- generate_fix_suggestions
- if_code_context:
- find_related_adrs
- find_related_nfrs
- get_change_history
- summarize_design_rationale
- if_impact_analysis:
- trace_forward_all_dependents
- categorize_by_type
- identify_affected_agents
- generate_impact_summary
- format_output
- return_debug_context
suggest_fix:
description: "Generate fix suggestion based on provenance"
steps:
- load_provenance_chain
- identify_mismatch_location
- extract_correct_specification
- generate_code_change
- validate_against_requirements
- return_suggestion
# Storage
storage:
debug_sessions: ".aiwg/logs/debug-sessions/"
provenance_cache: ".aiwg/provenance/debug-cache.json"
# Example debug session
example_debug_session: |
$ aiwg debug test/unit/auth/login.test.ts:42
Analyzing failure context for: test/unit/auth/login.test.ts:42
Test: "should reject invalid password"
Source: @src/auth/login-service.ts
Provenance chain:
Problem Statement (.aiwg/intake/solution-profile.md)
↓ derived-from
User Story (.aiwg/requirements/user-stories.md#US-003)
↓ elaborated-to
Use Case (.aiwg/requirements/use-cases/UC-001.md)
↓ specified-in
NFR Constraint (.aiwg/requirements/nfr-modules/security.md#password-policy)
"Passwords MUST be at least 12 characters" ← **Mismatch!**
↓ implemented-by
Implementation (src/auth/login-service.ts:validatePassword)
Current: minLength = 8 ← **Bug found**
Suggested fix:
File: src/auth/login-service.ts
Line: 25
Change: const minLength = 8; → const minLength = 12;
Reason: NFR-Security requires 12 character minimum
Time saved: ~12 minutes
# References
references:
research:
- "@.aiwg/research/findings/REF-058-r-lam.md"
- "@.aiwg/research/findings/REF-062-w3c-prov.md"
implementation:
- "#246"
related:
- "@agentic/code/frameworks/sdlc-complete/schemas/flows/provenance-framework.yaml"
- "@.claude/rules/mention-wiring.md"