Templates

Templates provide default body content when creating new requirements, helping maintain consistency across your requirements documentation.

Overview

When you create a new requirement using req add <KIND>, the tool looks for a template file in the .req/templates/ directory. If found, the template content is used as the body of the new requirement. The HRID is automatically generated, and the title can be provided via the --title flag or edited after creation.

Template Location

Templates are stored as markdown files in the .req/templates/ directory:

your-requirements/
├── .req/
│   └── templates/
│       ├── USR.md          # Template for USR requirements
│       ├── SYS.md          # Template for SYS requirements
│       └── AUTH-USR.md     # Template for AUTH-USR requirements
├── config.toml
├── USR-001.md
└── SYS-001.md

Template Matching

When creating a requirement, templates are matched in order of specificity:

1. Full prefix match: If creating AUTH-USR-001, looks for .req/templates/AUTH-USR.md
2. KIND-only match: If not found, looks for .req/templates/USR.md
3. No template: If neither exists, creates empty content

This allows you to:

• Define general templates for kinds (e.g., USR.md for all user requirements)
• Override with namespace-specific templates (e.g., AUTH-USR.md for auth user requirements)

Creating Templates

Templates should contain body content only, starting with level-2 headings (##). The level-1 heading with HRID and title is automatically generated by the tool.

Simple Text Template

The simplest template is just plain text:

[Describe the requirement here]

Save this as .req/templates/USR.md.

Structured Template

For more structure, use markdown sections starting with level-2 headings:

## Description

[Detailed description]

## Acceptance Criteria

- [ ] Criterion 1
- [ ] Criterion 2

## Notes

[Additional notes]

Important: Do not include a level-1 heading (#) in templates. The tool automatically generates the heading with the HRID.

Namespace-Specific Template

Create specialized templates for namespaced requirements:

## Security Considerations

[Describe security implications]

## Implementation

[Authentication mechanism details]

## Test Strategy

[How to verify this auth requirement]

Save this as .req/templates/AUTH-USR.md.

Using Templates

Automatic Template Application

When you create a requirement without content flags, the template body is automatically used:

# Without title - creates requirement with empty title and template body
req add USR

# With title - creates requirement with specified title and template body
req add USR --title "User Registration"

The generated file will have this structure:

---
_version: '1'
uuid: ...
created: ...
---
# USR-001 User Registration

[Template body content starts here]

Overriding Templates

Templates are ignored when you provide content via CLI flags:

# Template ignored - uses title and body from flags
req add USR -t "Custom Title" -b "Custom content"

# Template ignored - uses title from flag
req add USR -t "Custom Title"

# Template ignored - uses body from flag
req add USR -b "Custom content"

Examples

Software Project Templates

.req/templates/USR.md:

## Statement

[Describe the user-facing requirement]

## User Value

[Why does the user need this?]

## Acceptance Criteria

- [ ] Criterion 1
- [ ] Criterion 2

.req/templates/SYS.md:

## Statement

[Describe the system-level implementation requirement]

## Technical Notes

[Implementation details]

## Testing

[How to verify]

Aerospace Project Templates

.req/templates/URQT.md (User Requirements):

## Description

[User requirement description]

## Rationale

[Justification]

## Verification Method

[Test, Analysis, Inspection, or Demonstration]

.req/templates/SRQT.md (Software Requirements):

## Specification

[Detailed technical specification]

## Derived From

[Parent URQT reference]

## Verification Method

[Test method]

## Criticality

[DAL level]

Best Practices

Keep Templates Simple

Templates should provide structure without being overly prescriptive:

✓ Good: [Describe the requirement]

✗ Too prescriptive: The system SHALL [verb] [object] [condition]

Use Placeholders

Use square brackets for clear placeholders:

[Describe the requirement here]

**Rationale**: [Why is this needed?]

Team Conventions

Document your team's template conventions:

## Description
[One paragraph summary]

## Details
[Detailed specification with sub-sections as needed]

## Testing
[How to verify this requirement]

Version Control

Commit templates to version control alongside your requirements:

git add .req/templates/
git commit -m "Add requirement templates"

Updating Templates

Templates only affect new requirements. To update existing requirements:

1. Update the template file
2. Manually edit existing requirements to match (if desired)
3. Or use the template as a guide for new requirements only

Common Patterns

Minimal Templates

For projects that prefer freeform text:

[Requirement description]

Structured Templates

For projects requiring specific sections:

## Specification
[Technical details]

## Rationale
[Why this is needed]

## Verification
[How to test]

Compliance Templates

For regulated industries:

## Requirement
[Requirement text]

## Compliance
**Standard**: [e.g., DO-178C]
**Criticality**: [e.g., DAL A]

## Verification
**Method**: [Test, Analysis, Inspection, Demonstration]
**Criteria**: [Pass/fail criteria]

Troubleshooting

Template Not Being Used

Problem: Created requirement is empty even though template exists.

Check:

1. Template file is in .req/templates/ directory
2. Template filename matches KIND exactly (case-sensitive)
3. Template file has .md extension
4. You didn't use -t or -b flags (which override templates)

Wrong Template Being Used

Problem: Expected namespace-specific template but got general template.

Reason: Namespace-specific template file doesn't exist.

Solution: Create .req/templates/<NAMESPACE>-<KIND>.md

Example: For AUTH-USR-001, create .req/templates/AUTH-USR.md

Real-World Example

Want to see templates in action? Check out the templates used by the Requiem project itself:

• USR Template - User requirements template with Statement, Rationale, and Acceptance Criteria sections
• SYS Template - System requirements template with Statement, Implementation Notes, and Verification sections

These templates are used to create all requirements in the Example Project, demonstrating professional structure and best practices.