nighthawk-report-templates

name	nighthawk-report-templates
description	Markdown report templates for all three Nighthawk question types (architecture, bug, guidance). Use this skill when writing or evaluating a Nighthawk report.

Nighthawk Report Templates

Three templates — one per question type. Pick the one matching the QUESTION_TYPE from the Classifier output.

Writing Principles (all templates)

• Lead with the answer — TL;DR first, always. If you can't state the answer in 1-2 sentences, you don't understand it yet.
• Cite code, not concepts — File paths with line numbers (e.g., ARO-RP/pkg/util/azurezones/azurezones.go#L85-L100) over hand-waving.
• Be direct and assertive — State facts, not possibilities. "ARO enforces 3 AZs" not "ARO may require multiple AZs".
• End with action — Every report must tell the reader what to do next.
• No filler — Skip "In this document we will explore..." Just start.

---

Template: architecture

Use when the user wants to understand how something works.

# [Descriptive Title]

**Date**: YYYY-MM-DD
**Service**: AKS | ARO
**Topic**: [Key technical area]

## TL;DR

[1-2 sentence direct answer. No hedging.]

## Technical Details

[Main content organized by concept. Use subheadings.]

**Architecture**: [How components relate]
**Implementation**: [What the code actually does, with file paths and line numbers]
**Configuration**: [Relevant settings, API versions, CLI flags]

[Mermaid diagram if it clarifies architecture or flow]

## Code References

- [`repo/path/file.go#L123-L145`](https://github.com/org/repo/blob/main/path/file.go#L123-L145) — [what this code does]
- ...

## Next Steps

- [Actionable items — what should the reader do with this information?]

## References

### GitHub Source Code
- [Repo/File](URL) — Description

### Microsoft Learn
- [Article](URL) — Description

---

Template: bug

Use when the user is reporting or investigating an issue.

# [Descriptive Title — include "Bug" or "Issue"]

**Date**: YYYY-MM-DD
**Service**: AKS | ARO
**Topic**: [Key technical area]

## TL;DR

[1-2 sentence summary of the issue and its status/impact.]

## Summary

[What's happening, who reported it, what's affected.]

## Environment

- **Version**: [AKS/ARO version]
- **Configuration**: [Relevant cluster settings]

## Steps to Reproduce

1. [Step]
2. [Step]
3. ...

## Expected Behavior

[What should happen]

## Actual Behavior

[What actually happens. Include error messages verbatim.]

## Root Cause

[Technical explanation with code references. File paths and line numbers.]

## Workaround

[If any. Be specific about steps. State "None identified" if there isn't one.]

## Suggested Fix

[What should change in the code/service to resolve this.]

## Code References

- [`repo/path/file.go#L123-L145`](URL) — [what this code does]

## References

### GitHub Source Code
- [Repo/File](URL) — Description

### Microsoft Learn
- [Article](URL) — Description

---

Template: guidance

Use when the user wants recommendations or best practices.

# [Descriptive Title]

**Date**: YYYY-MM-DD
**Service**: AKS | ARO
**Topic**: [Key technical area]

## TL;DR

[1-2 sentence direct recommendation.]

## Recommendations

### [Topic Area 1]

[Prescriptive guidance with links to official docs, reference architectures, repos.]

### [Topic Area 2]

[Continue with clear sections per topic.]

[Mermaid diagram if it clarifies decision flow or architecture]

## Tools & Resources

- [Tool/Resource](URL) — [What it does and why it matters]
- ...

## Next Steps

- [Specific actions the reader should take]

## References

### Microsoft Learn
- [Article](URL) — Description

### GitHub
- [Repo/Resource](URL) — Description

---

Mermaid Diagram Guidelines

Include Mermaid diagrams when they genuinely clarify something — architecture relationships, process flows, decision trees. Skip them when the text is already clear.

Keep diagrams:

• Simple: 5-10 nodes maximum
• Focused: One concept per diagram
• Labeled: Clear node names and relationship descriptions

---

File Naming

notes/Nighthawk-YYYY-MM-DD-<topic>.md

• YYYY-MM-DD — today's date
• <topic> — kebab-case description (e.g., AKS-KMS-Encryption, ARO-Storage-Accounts, ARO-SKU-Discrepancy)