Author issues as structural tension charts — not bug reports.
Every issue begins with five questions. Each maps to a section:
| Question | Section | Function |
|---|---|---|
| What exists now? | Context | Ground the reader in current reality |
| What do I want to exist? | Desired State | Name the creation, not the problem |
| What moves me from one to the other? | Action Steps | Strategic secondary choices |
| What is the tension? | Structural Tension | Make the causal force visible |
| What is this related to? | Related | Weave kinship to other work |
## Context
[Current reality — what exists now. Factual, specific, no motivation language.]
## Desired State
[The creation you want to bring into being. Describe the result, not the process.]
## Action Steps
- [ ] [Strategic secondary choice 1]
- [ ] [Strategic secondary choice 2]
- [ ] [...]
## Structural Tension
**Current reality:** [one-line restatement]
**Desired state:** [one-line restatement]
## Related
- [issue/ceremony/repo references — kinship connections]
Frame the issue as something being brought into existence, not a problem being eliminated.
| ❌ Reactive | ✅ Generative |
|---|---|
| “Fix broken auth flow” | “Auth flow that honors session lifecycle” |
| “Missing docs for X” | “Guidance for X that agents can act on” |
| “Bug: list renders wrong” | “List rendering that preserves structural intent” |
Follow structural tension charting rules for current reality:
Follow desired outcome quality (Fritz):
Not a checklist. Each step should pass the test:
“If we took these steps, would we achieve this result?”
Each action step can telescope into its own structural tension chart (its own issue).
The two-line summary at the bottom makes the disequilibrium visible. This is the engine — without it, the issue is just a task list.
Issues don’t exist alone. Name the ceremonies, repos, other issues, and upstream/downstream dependencies. This is relational accountability applied to issue tracking.