The epic document format

This page is the reference for the markdown document that edhil import reads: an epic and its work items. It is written for the person or the assistant that writes the document, and for anyone who has to fix one that was refused. The way to arrive at such a document is described in Working with edhil.

The format is strict on purpose. A work item is implemented from its description alone, and edhil implement reads the verification commands back from that description, so every part has a fixed place. A document that does not follow the rules is refused as a whole, and every error is listed with its line.

Checking a document

There are three ways to check a document, and they apply the same rules:

edhil import epic-3.md --dry-run
python3 tools/edhil-validate/edhil_validate.py epic-3.md
python3 tools/edhil-validate/edhil_validate.py --only-work-items findings.md

The first needs edhil and shows a preview of what would be created. The second is one Python file with no other requirement, so it can run in a pipeline or in a session of an assistant that has no edhil. It prints nothing and exits with 0 when the document is valid, and prints one line FILE:LINE:COLUMN: code: message for each error otherwise. --only-work-items is for a document that adds work items to an epic that exists (see Work items only). Neither of them looks at the forge: that the project issue exists is only checked by edhil import.

The shape of a document

# Epic 5 - Journal storage

**Project:** #161
**Milestone:** M2 - Storage

The text of the epic.

---

## WI #5.1 - Create the tables

**Depends on:** nothing

### High level summary

What the work item does and why.

### Steps

The files to change and the code to write.

### Definition of done

1. The tables exist.

### Verification steps

```verify
yet cleanify
cargo test -p edhil
```

---

## WI #5.2 - Write the first entry

**Depends on:** WI #5.1

### High level summary

Builds on WI #5.1.

### Steps

...

### Definition of done

1. ...

### Verification steps

```verify
yet prepush
```

A document is a list of blocks. The first block is the epic and the others are work items. A work item is a block of four sections, the last of which holds the commands that verify it.

Characters

A document may contain printable ASCII, tabs, line breaks and the accented letters of Latin-1 (U+00C0 to U+00FF, without the multiplication and division signs). Every other character is the error non_ascii. The message suggests the ASCII text for the usual ones: write - for an en dash or an em dash, -> for an arrow, straight quotes for curly quotes and ... for an ellipsis. The same rule holds for the book and for the descriptions that edhil creates.

Blocks and rules

The document is split on lines that hold three or more hyphens and nothing else (---, -----), with spaces or tabs around them allowed. A line like that inside a fenced code block is ordinary text and does not split. Put a rule between the epic and the first work item, and between all the work items.

A fenced code block starts with a line of three or more backticks (or tildes), indented by at most three spaces, and ends with a line of the same character that is at least as long. To show a block that contains fences, such as a work item inside a diff, open it with a longer fence (four backticks around three). A fence that is never closed is the error unclosed_fence, reported at the line where it opened.

A block that has no work item heading, other than the first one, is ignored.

The epic block

The first block starts with the title of the epic:

# Epic 5 - Journal storage

The heading can also be written # Title. The part Epic N - is removed, so the epic above is called Journal storage. The separator is a run of one or more hyphens. A heading without a title is no_epic_title. A document that starts with something else is refused, and an empty document is empty.

Right after the heading come the metadata lines, one **Key:** value (or Key: value) per line, with blank lines allowed between them. The first line that is not a metadata line ends the metadata. Keys are not case sensitive, and a key given twice is duplicate_metadata.

Key Meaning
Project Required. The number of the project issue in the forge that the epic belongs to, written #161 or 161. The project is an issue with the Projects label that you create by hand; its title becomes the label of the epic and its work items. Missing is missing_project, and a value that is not a positive number is invalid_project.
Milestone Free text, usually the name of the milestone of the implementation plan. edhil keeps it in the description and does not interpret it.

Any other key is kept as text in the description in the same way. The rest of the block, as long as you like, is the description of the epic. Put there what every work item depends on, because the agent only sees the work item it is implementing: the decisions for the whole epic, the order of the work items, the rules for the code.

The work item block

The heading

## WI #5.1 - Create the tables

## WI 5.1 - Title and ## Issue #5.1 - Title are read in the same way. 5.1 is the identifier of the work item in the document: the number of the epic, a dot and the number of the work item. It is used to link the work items to each other and to show them in the preview, and it must be unique in the document (duplicate_work_item_id). The identifier and the title are separated by a run of ASCII hyphens, and hyphens inside the title are kept. An em dash does not separate. A heading that starts with ## WI or ## Issue and cannot be read is bad_work_item_heading.

The work items run in the order of the document. Number and place them in the order in which they have to be implemented.

The metadata

As in the epic, **Key:** value lines may follow the heading. The usual one is **Depends on:**, with nothing or the work items that must come first. Project is not allowed here, because a work item takes the project of its epic (project_on_work_item).

The four sections

After the metadata come four sections, each introduced by a level 3 heading, exactly in this order and spelt like this:

Section What it holds
### High level summary The goal in plain sentences, then what the work item does. It must make sense without any other document.
### Steps The files to change with their paths, the code to insert or change as a diff or a full snippet, and the unit tests to write.
### Definition of done Numbered criteria that someone other than the author can check.
### Verification steps The commands that verify the work item, in one verify block.

Between the metadata and the first section only blank lines are allowed (text_before_sections). Every section must be present (missing_section), once (duplicate_section), in this order (section_order) and not empty (empty_section). A level 3 heading with another name is unknown_section, and the message suggests the right name when it is a misspelling such as ### High-level summary. Use level 4 headings (####) for the structure inside a section. Level 3 headings inside a fenced block are text.

The verification block

The Verification steps section holds exactly one fenced block whose label is verify (no_verify_block, multiple_verify_blocks), and it has at least one command (empty_verify_block):

### Verification steps

```verify
yet cleanify
cargo test -p edhil
yet prepush
```

Each line is one command. Blank lines and lines that start with # are skipped. A line is split into words the way a shell does for plain commands, but there is no shell: the program is started directly, in the root of the repository.

  • Spaces and tabs separate words.
  • Text in single quotes is literal. In double quotes a backslash escapes only " and \. Outside quotes a backslash escapes the next character.
  • A quote that is not closed is unterminated_quote.
  • The characters |, &, ;, <, >, `, $, ( and ) outside quotes are shell_syntax: pipes, &&, redirections, variables and substitutions do not exist. To use them, put them in a script or a task of the project and run that.

The commands run in the order written. Each is a step of its own, and the first one that fails stops the verification; after a fix the verification starts again from the first command. A command that the project does not allow in integration.verification.restrict makes the work item impossible to implement, so write only commands that the project has. Put the quick commands first. Text before and after the block in the section is allowed, and is kept.

References between work items

In the description of a work item, WI #5.1 and #5.1 refer to another work item of the document by its identifier. After the issues are created they are rewritten to the real issue numbers. A reference to an identifier that is not in the document is left alone. The heading line of a work item is never rewritten, because edhil implement has to read it back.

What import creates

For a new epic: the epic issue and one issue for each work item, with the text of the block as description, the labels Epics or Work Items and the label of the project, and the links between them. Each work item description ends with the line Parent Epic: #N, which the parser accepts after the verification block. The description in the forge is the source of truth from then on: if you edit it there, keep the format, because edhil implement reads the commands from it and refuses a description that does not follow it. See edhil import for the options and for what happens when the forge fails.

Work items only

A document with only work items, with no epic block, adds work items to an epic that already exists:

edhil import findings.md --epic 123
python3 tools/edhil-validate/edhil_validate.py --only-work-items findings.md

It has no Project line, because the project is found through the links of the epic. An epic heading in such a document is epic_not_allowed. This is how the findings of a review become work items of an epic that is already imported.

The error codes

Every error has a code that does not change, so that a script can act on it. The line is counted from 1 from the start of the document.

Code Meaning
empty The document is empty.
no_epic_title The epic heading has no title.
epic_not_allowed An epic block in a document of work items only.
bad_work_item_heading A ## WI or ## Issue heading that cannot be read: no identifier, or no hyphen between the identifier and the title.
duplicate_work_item_id Two work items have the same identifier.
missing_project The epic has no Project line.
invalid_project The Project value is not a positive number.
project_on_work_item A work item has a Project line.
duplicate_metadata A key is given twice in the metadata of a block.
text_before_sections Text between the metadata and the first section.
missing_section One of the four sections is missing.
duplicate_section A section is given twice.
section_order The sections are not in the order of the table.
unknown_section A level 3 heading that is not one of the four.
empty_section A section has no text.
unclosed_fence A code fence is never closed.
no_verify_block No verify block in the Verification steps.
multiple_verify_blocks More than one verify block.
empty_verify_block The verify block has no command.
unterminated_quote A quote in a command is not closed.
shell_syntax A shell character outside quotes in a command.
non_ascii A character that is not allowed.

A checklist for the writer

  • The first line is # Epic N - Title, followed by **Project:** #N.
  • Every work item has the heading ## WI #N.M - Title and the four sections, spelt as in the table, in order, none empty.
  • Every Verification steps section has one verify block with plain commands that the project allows, the quick ones first.
  • Rules (---) separate the blocks, and no rule is left inside a section outside a fence.
  • Blocks that contain fences are wrapped in a longer fence.
  • The text is ASCII, apart from Latin-1 letters.
  • edhil import --dry-run or edhil_validate.py prints no error.