Fix heading hierarchy in spike and spec doc templates

Author: max-svistunov

docs/contributing/templates/spec-doc-template.md

@@ -11,31 +11,31 @@ TODO (example, delete): [conversation-compaction.md](../../design/conversation-c
 | **Spike**          | TODO: [LCORE-XXXX](https://redhat.atlassian.net/browse/LCORE-XXXX) |
 | **Links**          | TODO                                      |
 
-# What
+## What
 
 TODO: What does this feature do?
 
-# Why
+## Why
 
 TODO: What problem does this solve? What happens today without it?
 
-# Requirements
+## Requirements
 
 TODO: Numbered, testable requirements. For each, it should be easy to provide clear acceptance criteria.
 
 - **R1:**
 - **R2:**
 
-# Use Cases
+## Use Cases
 
 TODO: User stories in "As a [role], I want [X], so that [Y]" format.
 
 - **U1:**
 - **U2:**
 
-# Architecture
+## Architecture
 
-## Overview
+### Overview
 
 TODO: Flow diagram showing the request/response path with the new feature.
 
@@ -45,15 +45,15 @@ TODO: flow diagram
 
 TODO: Add subsections below for each relevant component. Delete any that don't apply, add feature-specific ones.
 
-## Trigger mechanism
+### Trigger mechanism
 
 TODO: When and how the feature activates.
 
-## Storage / data model changes
+### Storage / data model changes
 
 TODO: Schema changes, which backends need updates.
 
-## Configuration
+### Configuration
 
 TODO: YAML config example and configuration class.
 
@@ -65,45 +65,45 @@ TODO: config example
 TODO: configuration class
 ```
 
-## API changes
+### API changes
 
 TODO: New or changed fields in request/response models.
 
-## Error handling
+### Error handling
 
 TODO: How errors are surfaced — new error types, HTTP status codes, recovery behavior.
 
-## Security considerations
+### Security considerations
 
 TODO: Auth, access control, data sensitivity implications. Remove if not applicable.
 
-## Migration / backwards compatibility
+### Migration / backwards compatibility
 
 TODO: Schema migrations, API versioning, feature flags for gradual rollout. Remove if not applicable.
 
-# Implementation Suggestions
+## Implementation Suggestions
 
-## Key files and insertion points
+### Key files and insertion points
 
 TODO: Table of files to create or modify.
 
 | File | What to do |
 |------|------------|
 | TODO | TODO       |
 
-## Insertion point detail
+### Insertion point detail
 
 TODO: Where the feature hooks into existing code — function name, what's available at that point, what the code should do.
 
-## Config pattern
+### Config pattern
 
 All config classes extend `ConfigurationBase` which sets `extra="forbid"`.
 Use `Field()` with defaults, title, and description.  Add
 `@model_validator(mode="after")` for cross-field validation if needed.
 
 Example config files go in `examples/`.
 
-## Test patterns
+### Test patterns
 
 - Framework: pytest + pytest-asyncio + pytest-mock.  unittest is banned by ruff.
 - Mock Llama Stack client: `mocker.AsyncMock(spec=AsyncLlamaStackClient)`.
@@ -113,21 +113,21 @@ Example config files go in `examples/`.
 
 TODO: Describe any feature-specific test considerations (e.g., tests that need a running service, special fixtures, concurrency testing).
 
-# Open Questions for Future Work
+## Open Questions for Future Work
 
 TODO: Things explicitly deferred and why.
 
--
--
+- TODO
+- TODO
 
-# Changelog
+## Changelog
 
 TODO: Record significant changes after initial creation.
 
 | Date | Change | Reason |
 |------|--------|--------|
 |      | Initial version |        |
 
-# Appendix A
+## Appendix A
 
 TODO: Supporting material — PoC evidence, API comparisons, reference sources. Add appendices as needed.

docs/contributing/templates/spike-template.md

@@ -2,20 +2,20 @@ TODO (example, delete): [conversation-compaction-spike.md](../../design/conversa
 
 # Spike for TODO: feature name
 
-# Overview
+## Overview
 
 **The problem**: TODO
 
 **The recommendation**: TODO
 
 **PoC validation**: TODO
 
-# Decisions for TODO specify reviewer(s)
+## Decisions for TODO specify reviewer(s)
 
 These are the high-level decisions that determine scope, approach, and cost.
 Each has a recommendation — please confirm or override.
 
-## Decision 1: TODO title
+### Decision 1: TODO title
 
 TODO: Context, options table, recommendation. Link to the relevant background section(s) below.
 
@@ -26,17 +26,17 @@ TODO: Context, options table, recommendation. Link to the relevant background se
 
 **Recommendation**: TODO
 
-# Technical decisions for TODO specify reviewer(s)
+## Technical decisions for TODO specify reviewer(s)
 
 Architecture-level and implementation-level decisions.
 
-## Decision N: TODO title
+### Decision N: TODO title
 
 TODO: Context, options table, recommendation. Link to the relevant background section(s) below.
 
 **Recommendation**: TODO
 
-# Proposed JIRAs
+## Proposed JIRAs
 
 TODO: One subsection per JIRA. Each JIRA's agentic tool instruction should point to the spec doc (the permanent reference), not this spike doc.
 
@@ -61,23 +61,23 @@ Read the "[section]" section in docs/design/<feature>/<feature>.md.
 Key files: [files].
 ```
 
-# PoC results
+## PoC results
 
 TODO: If a PoC was built, document what it does, what it proved, and how it diverges from the production design.
 
-## What the PoC does
+### What the PoC does
 
 **Important**: The PoC diverges from the production design in these ways:
 - TODO
 
-## Results
+### Results
 
 TODO
 
-# Background sections
+## Background sections
 
 TODO: Research and analysis that supports the decisions above. These sections are linked from the decisions, not read front-to-back. Common topics: current architecture, existing approaches, design alternatives. Add or remove as needed.
 
-# Appendix A
+## Appendix A
 
 TODO: Supporting material — external references, responses to suggestions from team members. Add appendices as needed.