Skip to content

Add unit context to audit.md logging format for multi-unit workflow traceability #72

@junsjang

Description

@junsjang

Problem

When working on projects with multiple units in the Construction phase, the audit.md file lacks unit-specific context, making it difficult to trace which interactions belong to which unit. This becomes particularly problematic when merging work from parallel unit development or analyzing the audit trail retrospectively.

Observed Behavior

Current audit.md logging format as defined in core-workflow.md:

## [Stage Name or Interaction Type]
**Timestamp**: [ISO timestamp]
**User Input**: "[Complete raw user input - never summarized]"
**AI Response**: "[AI's response or action taken]"
**Context**: [Stage, action, or decision made]

The Context field is defined generically as "Stage, action, or decision made" without explicit guidance to include unit identification. When multiple units are processed:

  • All unit interactions are logged to a single audit.md file
  • No clear indication of which unit each log entry belongs to
  • Difficult to filter or analyze interactions by unit
  • Challenging to understand the sequence of events for a specific unit

Root Cause

  • Missing specification: No explicit requirement to include unit name in audit log entries
  • Generic context definition: The Context field description doesn't mandate unit identification
  • Documentation gap: Construction phase files (functional-design.md, code-generation.md, etc.) only specify "Log approval in audit.md with timestamp" without unit context requirements
  • Single file design: While audit.md is intentionally a single file for complete audit trail, the format doesn't accommodate multi-unit scenarios

Proposed Solution

Update Context field specification in core-workflow.md

Modify the existing "Prompts Logging Requirements" section in core-workflow.md to clarify Context field usage:

Current text:

- Include stage context for each entry

Updated text:

- Include stage context for each entry
- **For Construction phase per-unit stages**: Include unit name in Context field (e.g., "CONSTRUCTION - Code Generation - Unit: user-service")

Add one example in core-workflow.md

Add a single example showing unit context usage in the existing "Audit Log Format" section:

### Audit Log Format:
```markdown
## [Stage Name or Interaction Type]
**Timestamp**: [ISO timestamp]
**User Input**: "[Complete raw user input - never summarized]"
**AI Response**: "[AI's response or action taken]"
**Context**: [Stage, action, or decision made]

---

Example with unit context:

## Code Generation
**Timestamp**: 2024-02-09T14:30:00Z
**User Input**: "Approve code generation plan"
**AI Response**: "Code generation plan approved"
**Context**: CONSTRUCTION - Code Generation - Unit: user-service

---

Affected Files

Core workflow files:

  • aidlc-rules/aws-aidlc-rules/core-workflow.md (Primary change - audit log format)

Metadata

Metadata

Assignees

Labels

No labels
No labels

Type

No type

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions