nighthawk-report-templates

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