# ITD Template

|            |               |
| ---------- | ------------- |
| **Author** | \[Name]       |
| **Date**   | \[Month Year] |

***

> **Note:** Author and Date are optional—omit them when the ITD is part of a Spec (the Spec has its own metadata).
>
> **Category Examples**: FOUNDATION, PROCESS, AUTHORING, SECURITY, DATA, INFRA
>
> **Naming**: Use uppercase categories with lowercase descriptors (e.g., `SECURITY-ITD-001-encryption-strategy.md`)

## CONTEXT

Background information and situational context. Why is this decision needed?

* What problem are we trying to solve?
* What's the current state?
* What constraints do we have?

## PROBLEM

Frame as a clear, answerable question:

* "How should we implement authentication across multiple client types?"
* "Which database should we use for high-volume event storage?"
* "What framework should we use for building our web application?"

## OPTIONS CONSIDERED

List all options you evaluated. Mark the selected option with ✅ and bold:

1. ✅ **\[Selected Option]**: Brief description of this approach
2. \[Alternative Option 1]: Brief description of this approach
3. \[Alternative Option 2]: Brief description of this approach

## REASONING

Explain why the selected option was chosen AND why each alternative was rejected.

*Option 1 (Selected):* \[Why this was chosen - specific technical reasons, evidence, how it fits context]

*Option 2:* \[Why rejected - specific limitations or trade-offs that weren't acceptable]

*Option 3:* \[Why rejected - specific limitations or trade-offs that weren't acceptable]

## IMPLICATIONS

* \[Actionable consequence 1 - what must be done]
* \[Actionable consequence 2 - what changes are required]
* \[Constraint or requirement]
* \[Separate decisions needed downstream]

## IMPLEMENTATION NOTES (Optional)

\[Technical details, configuration examples, or additional context that helps with implementation. Use this section for content that doesn't fit elsewhere but is useful for engineers implementing the decision.]

***

## Tips for Writing Good ITDs

### AI-Assisted Writing Guidelines

**AI/LLM Usage Encouraged**: Use AI to help structure reasoning, generate examples, and improve clarity. Authors remain fully accountable for all technical content and accuracy.

### CONTEXT Section

* Explain the "why now" - what triggered this decision?
* Include relevant constraints (timeline, budget, team size)
* Keep it brief - detailed analysis goes in REASONING

### PROBLEM Section

* Frame as a specific, answerable question
* Avoid solution hints in the problem statement
* Make it clear what decision needs to be made

### OPTIONS CONSIDERED Section

* List ALL options you seriously evaluated (not just 2)
* Mark the selected option with ✅ and **bold** (e.g., `1. ✅ **Option Name**: description`)
* Give each option a brief, neutral description
* Present options on equal footing (no bias in descriptions)

### REASONING Section

* This is the heart of the ITD - take your time here
* Explain why the winner was chosen with specific technical reasons
* Address each rejected alternative explicitly
* Include evidence when possible (benchmarks, metrics, references)
* **Evidence accessibility**: Copy relevant excerpts from sources and link the original — not all readers have access to every system
* Explain why this fits your specific context
* Be honest about trade-offs

### IMPLICATIONS Section

* Focus on actionable items
* Include costs, risks, and dependencies
* Note downstream decisions that need to be made
* Mention training/documentation needs

### Inline References

* Link to related ITDs and documents **inline where mentioned** (not in a separate References section)
* Example: "This builds on [FOUNDATION-ITD-002](https://github.com/Lost-Hex/lost-hex-base/blob/main/docs/templates/path/to/file.md) which established..."
* External links (articles, benchmarks) should also be inline where relevant

### Rendering Check

* **Preview in GitBook** after merge to verify rendering
* Run `npm run lint:markdown` locally to catch structure issues before PR


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://losthex.gitbook.io/losthex-docs/templates/itd-template.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.