Context format template - GitWhy

When you tell your agent “save this session with GitWhy,” the agent generates a structured markdown document using this template, then saves it with git why save or the gitwhy_save MCP tool.

Full template

# [Title of what was done]

**Context ID:** ctx_a1b2c3d4
**Saved by:** @developer-name
**Agent:** claude-code (claude-sonnet-4-6)
**Repository:** owner/repo-name
**Branch:** feature/auth-middleware
**Date:** 2026-02-22T15:30:00Z

## Prompt
> The original user prompt that initiated this work.
> Can be multi-line. Quoted verbatim.

## What Was Done
- Created JWT middleware for token verification
- Added login route with token signing
- Updated package.json with jsonwebtoken dependency

## Reasoning
Chose JWT over session cookies because the application is API-only
with no browser-based frontend. JWTs are stateless and fit the
existing service architecture without requiring a session store.

## Key Decisions
- **Token expiry:** 24 hours — balances security vs UX for internal tool
- **Algorithm:** RS256 — allows key rotation without redeploying consumers
- **Storage:** No refresh tokens in v1 — simplifies implementation

## Rejected Alternatives
- **Session cookies:** Rejected — requires session store, not suitable for API-only service
- **OAuth2 with external provider:** Rejected — overkill for internal service
- **Paseto tokens:** Considered but team is more familiar with JWT ecosystem

## Risks & Open Questions
- No rate limiting on the login endpoint yet — could be brute-forced
- Token revocation not implemented — if a token is compromised, it's valid for 24h
- Should we add refresh tokens before launch?

## Files
- `src/auth/middleware.ts` — new — Token verification middleware
- `src/routes/login.ts` — modified — Added token signing on login
- `package.json` — modified — Added jsonwebtoken dependency

## Commits
<!-- Auto-populated by GitWhy CLI from post-commit hook -->
- `a1b2c3d` Add JWT auth middleware
- `d4e5f6a` Wire up login token flow
- `e7f8g9h` Add jsonwebtoken to dependencies

## Verification
- All tests passing (14 passed, 0 failed)
- Build successful
- Manual test: login → token → protected route → 200 OK

Section reference

Section	Required	Auto-populated	Description
Title + metadata	Yes	Context ID and Date are auto-generated	What was done and who did it
`## Prompt`	Yes	No	The original user prompt, quoted verbatim
`## What Was Done`	Yes	No	Bulleted list of actions taken
`## Reasoning`	Yes	No	Why this approach was chosen over alternatives
`## Key Decisions`	Optional	No	Binary choices made and rationale
`## Rejected Alternatives`	Optional	No	What was considered and why rejected
`## Risks & Open Questions`	Optional	No	Uncertainties flagged during the work
`## Files`	Yes	No	Files changed with status (new/modified/deleted)
`## Commits`	Auto-populated	Yes — from `.gitwhy/.active-commits`	Commit SHAs and messages
`## Verification`	Optional	No	Test results, build status, manual tests

Metadata fields

The metadata block immediately after the title is required:

**Context ID:** ctx_a1b2c3d4
**Saved by:** @developer-name
**Agent:** claude-code (claude-sonnet-4-6)
**Repository:** owner/repo-name
**Branch:** feature/auth-middleware
**Date:** 2026-02-22T15:30:00Z

Context ID — assigned by the CLI on save. The agent writes a placeholder (ctx_ prefix); the CLI replaces it with the real ID.
Date — ISO 8601 timestamp. The agent writes the current time; the CLI validates and normalizes it.
Saved by — the developer’s GitHub username or name.
Agent — the agent name and model, in the format agent-name (model-version).

Validation

When you run git why save, the CLI validates that these required sections are present:

## Prompt
## What Was Done
## Reasoning
## Files

If any are missing, the save fails with a message identifying which sections to add.

See also

Examples — a complete, well-written context
Tips for agents — how to get good context output from your agent