Skip to content

[Feature]: Enhance ADR Creation Workflow with Placement Planning and Quality Standards #68

@WilliamBerryiii

Description

@WilliamBerryiii

Issue Description

Enhance the ADR creation chatmode to improve the architectural decision documentation workflow by:

  1. Template Path Updates: Correct references to point to local template at docs/templates/adr-template-solutions.md
  2. Early Placement Planning: Add placement question to Phase 1 Discovery to establish ADR location before drafting
  3. Version Numbering: Implement -v01, -v02 format for tracking iterations and multiple decisions per day
  4. Quality Patterns: Apply prompt-builder XML-style blocks for extractability and consistency
  5. Markdown Standards: Integrate markdown compliance guidance throughout the workflow

Implementation Tasks

Phase 1: Template Path Updates ✅ COMPLETED

  • Update Phase 2 Research Integration template reference
  • Update Phase 4 Solution Library Compliance template reference

Phase 2: Add ADR Placement Question ✅ COMPLETED

  • Insert comprehensive placement planning subsection in Phase 1 Discovery
  • Add dialogue pattern with recommended locations (docs/decisions/)
  • Include version numbering guidance (-v01, -v02 format)
  • Update Research Phase to reference user-chosen ADR location
  • Simplify Phase 4 Document Placement to reference earlier decision

Phase 3: Apply Prompt-Builder Quality Patterns

  • Wrap opening questions in XML-style block
  • Wrap working draft pattern in XML-style block
  • Add template reference block with XML wrapping
  • Add dialogue pattern blocks for placement question
  • Add example coach response blocks

Phase 4: Add Quality Gates and Validation

  • Insert comprehensive Quality Gates section
  • Add Output Formatting Standards section
  • Define validation checkpoints

Phase 5: Integrate Markdown Standards Compliance

  • Add Markdown Standards Compliance subsection to Phase 4
  • Reference YAML frontmatter requirements
  • Reference heading conventions and formatting rules

Benefits

  • Consistency: Early placement planning ensures ADRs are organized from the start
  • Discoverability: Version numbering handles multiple decisions and iterations clearly
  • Quality: XML-style blocks enable pattern extraction and reuse
  • Compliance: Integrated markdown standards ensure high-quality documentation
  • Efficiency: Reduces redundancy by capturing placement decision once

Related Files

  • .github/chatmodes/adr-creation.chatmode.md - ADR creation coach chatmode
  • docs/templates/adr-template-solutions.md - ADR template
  • .github/instructions/markdown.instructions.md - Markdown standards
  • .github/chatmodes/prompt-builder.chatmode.md - Quality patterns reference

Additional Context

This enhancement builds on the successful ADR template migration from edge-ai repository and establishes comprehensive quality patterns for consistent, high-quality architectural decision documentation across the HVE Core project.

Progress: Phases 1-2 complete (template paths updated, placement planning added with versioning). Phases 3-5 remaining (quality patterns, validation gates, markdown standards integration).

Related Plan: .copilot-tracking/plans/20251118-adr-template-migration-plan.instructions.md
Changes Log: .copilot-tracking/changes/20251118-adr-template-migration-changes.md

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentationenhancementNew feature or requestneeds-triageRequires triage and prioritization

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions