# render-gate

> Runs a test-driven rendering loop for Copier templates, writing E2E assertions first and iterating until every flavor renders cleanly before committing.

- Skill: `samyakjhaveri/render-gate` (Agent Skill)
- Install (CLI): `npx skillmds add samyakjhaveri/render-gate`
- Raw SKILL.md: https://api.skillmd.com/api/skills/samyakjhaveri/render-gate/raw
- Safety review: CAUTION (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools, Testing & QA
- Tags: Copier, E2e Testing, Jinja, Rendering, Tdd, Template, Yaml
- Author: SamyakJhaveri (https://skillmd.com/u/samyakjhaveri)
- Updated: 2026-08-22
- Page: https://skillmd.com/skills/samyakjhaveri/render-gate

---


# Render Gate: TDD Template Rendering

A test-driven development loop for Copier template work. The agent writes rendering
assertions first, then iterates until every flavor passes.

## When to Use

- Editing `copier.yml`, `*.jinja` files, or flavor overlays
- Adding a new Copier question or choice
- Modifying the `_subdirectory`, `_tasks`, or `_templates_suffix` config
- After any change that could affect how the template renders

## When NOT to Use

- Non-template projects → use `/validate`
- Runtime code changes that don't affect template rendering
- Documentation-only edits

## Procedure

### Step 1: Establish the test baseline

Check if `bin/verify-template.sh` exists and what it covers:

```bash
[ -x bin/verify-template.sh ] && echo "verify-template.sh exists" || echo "no verify script"
cat bin/verify-template.sh 2>/dev/null | head -30
```

### Step 2: Write or extend E2E assertions

If `bin/verify-template.sh` exists, use it as the base. If it doesn't cover the
current change, extend it. The assertions must verify:

1. **Every flavor renders** — each combination of Copier choices produces output
2. **Answers file is valid** — `.copier-answers.yml` exists and contains expected keys
3. **Choices mappings are correct** — conditional includes/excludes match the choices
4. **YAML scalars are well-formed** — no unquoted colons, no broken folded scalars
5. **Jinja syntax is valid** — no unclosed tags, no undefined variables

Render from **committed git state** (not working tree) to match Copier's behavior:

```bash
TMPDIR=$(mktemp -d)
uvx copier copy --trust --vcs-ref HEAD --defaults . "$TMPDIR/test-default" 2>&1
echo "Exit code: $?"
ls -la "$TMPDIR/test-default/"
```

### Step 3: Run the full suite and record failures

```bash
bin/verify-template.sh 2>&1
echo "Exit code: $?"
```

### Step 4: Iterative fix loop

For each failure:
1. Read the error output
2. Identify the root cause in the template source
3. Fix the template file
4. Re-run the **full suite** (not just the failing test)
5. Report: what failed, what you fixed, current pass/fail status

**Hard rule:** Never commit while any test is failing. The loop continues until
exit code 0.

### Step 5: Final verification

After all tests pass:

```bash
bin/verify-template.sh 2>&1
echo "Final exit code: $?"
```

Only proceed to commit if exit code is 0. Report the full pass summary.

## Common Failure Patterns

| Symptom | Likely Cause |
|---------|-------------|
| `copier copy` fails with "not a git repo" | Need `--vcs-ref HEAD`; template must be committed |
| YAML parse error in rendered output | Unquoted colon in a Jinja variable or description field |
| Missing file in rendered output | Conditional include/exclude doesn't match the flavor choices |
| `.copier-answers.yml` missing keys | New question added to `copier.yml` without a default |
| Jinja `UndefinedError` | Variable name mismatch between `copier.yml` and template |