# `.grump` format and survey format choice

Version 1

Read before creating or editing `.grump`, or when an authorized survey needs
the format choice. Reading these rules does not start a survey. The Q001
question below applies only to an initial survey; during a requested re-survey,
ask about format only if missing, invalid, or explicitly being reconsidered.

`.grump` is project-local Markdown generated by the survey and then owned by
the people maintaining the project. Store durable project context, not generic
GrumpyDev instructions, an installation inventory, or a survey transcript.

For exact preference fields, values, defaults, and scope, use the installed
[review-preferences.md](../../grumpydev/references/review-preferences.md)
before interpreting or recording preferences. Do not copy that definition
table into the project file.

## Ask Q001

After inspecting project evidence, ask this as the first survey question:

```text
Q001. For future GrumpyDev work in this project, should `.grump` use the most
compact form that preserves all material meaning, or keep more explanation and
rationale? Reply `compact` or `detailed`.
```

Record `Doctrine format: compact` or `Doctrine format: detailed` only after an
explicit project-wide answer. If the user declines, defers, or answers
ambiguously, use compact as the serialization fallback but do not store a
fabricated preference.

## Apply the choice

Compact doctrine uses short structured bullets, records each fact once, points
to project documents instead of copying them, and retains only rationale needed
to apply a constraint or decision correctly. It must preserve material purpose,
requirements, constraints, decisions, evidence, runtime and deployment facts,
specialist exceptions, unknowns, and exact review preferences.

Detailed doctrine may retain more decision rationale, alternatives, evidence
scope, and operational explanation. It still removes repeated facts, generic
GrumpyDev rules, survey transcripts, and resolved questions.

Both forms preserve stable identifiers and distinctions among confirmed facts,
inference, contradiction, staleness, and unresolved facts. Compact does not
mean vague. Detailed does not mean duplicative. A format change must preserve
meaning and human-authored content.

## Default structure

Use this order for generated content. Omit empty optional sections rather than
adding placeholder text.

```text
# GrumpyDev project doctrine

## Purpose
## Requirements
## Constraints
## Accepted decisions
## Project evidence
## Runtime and deployment
## Specialist exceptions
## Unknowns
## Review preferences
```

- `Purpose` states what the project is for, who or what it serves, and material
  success conditions when known.
- `Requirements` records durable behavior or outcomes future work must preserve.
- `Constraints` records limits the project cannot freely change.
- `Accepted decisions` records choices and tradeoffs that should not be
  relitigated without new evidence or an explicit request.
- `Project evidence` points to documents, code, configuration, tests, or user
  statements that establish material doctrine.
- `Runtime and deployment` records only environment facts that can change
  engineering judgment.
- `Specialist exceptions` records the exact `gd-` name of an installed
  specialist that project evidence explicitly makes inapplicable. It is not a
  catalog or installation inventory.
- `Unknowns` records unresolved facts that can materially change a future
  review.
- `Review preferences` contains only fields defined by the preference reference.

Human authors may add other sections. GrumpyDev must preserve unknown content
and must not treat it as operating policy unless the preference reference
defines it.

## Stable identifiers

Use an identifier only when an item needs a durable cross-session reference:

- `CON-###` for a hard constraint;
- `DEC-###` for an accepted decision or tradeoff;
- `UNK-###` for a material unresolved fact;
- `DEP-###` only when the project has more than one materially different
  deployment or execution profile; and
- `INF-###` only when shared infrastructure needs a stable cross-reference.

A short fact that is never referenced needs no identifier. Preserve an
identifier through clarification or rename. Do not recycle an identifier for a
different item. When resolving an unknown, preserve its history or link it to
the resulting constraint or decision rather than silently reusing its number.

## Evidence and uncertainty

Material factual doctrine must identify a useful evidence locator and stay
within that source's real scope. Concise inline notation is sufficient. Keep
these states distinct when they matter:

- `confirmed`: directly supported by inspected evidence or an explicit user
  statement at the stated scope;
- `inferred`: reasoned from named evidence but not stated directly;
- `contradictory`: inspected sources disagree;
- `stale`: the source may no longer describe the current project; and
- `unresolved`: the available evidence does not establish the fact.

An explicit user decision is authoritative as a project decision without
pretending it proves an external runtime. A repository file proves what it
declares, not what a customer, vendor, or deployed environment uses. Never
invent a source or promote inference to confirmed fact for a cleaner document.

## Bounded editing rules

Because `.grump` is human-owned, GrumpyDev edits only recognized fields and
sections required by the current authorized operation. It must:

1. inspect the current file and its encoding before editing;
2. preserve unknown sections, comments, wording, ordering, and identifiers;
3. change only content supported by inspected evidence or an explicit durable
   user decision;
4. never normalize or delete surrounding content merely to match this default
   layout;
5. preserve the established line-ending convention and final newline; and
6. reread the result before claiming the write succeeded.

If a bounded change cannot preserve surrounding human content safely, leave the
file unchanged and return the exact proposed change in chat.

## Minimal example

Illustration only, not evidence about the current project. These two preference
values assume explicit project-wide answers; do not store defaults as answers.

```markdown
# GrumpyDev project doctrine

## Purpose

- Provide local review guidance for engineering plans in this repository.

## Constraints

- CON-001: The published site remains static. Source: user answer Q002.

## Review preferences

- Doctrine format: compact
- Plan addenda: chat only
```