Add AGENTS.md with a literature-grounded writing/review checklist #170

Merged

mahesh-panchal merged 3 commits from chore/add-agents-md into main

2026-09-01 19:26:38 +00:00

mahesh-panchal commented

2026-08-24 13:37:24 +00:00

(Migrated from github.com)

Description

Adds AGENTS.md at the repo root: a single instruction set any coding agent can use to write or review a walkthrough post, covering repo conventions (post structure, frontmatter, draft: true, branch naming) plus a 15-item review checklist grounded in cognitive load theory, the Diátaxis framework, Mayer's multimedia learning principles, Carroll's minimalism, and related literature. Every citation was checked against the source to confirm it actually supports the claim next to it, not just asserted.

Also:

Adds the draft: true convention and the post-independence rule to write-up.qmd.
Syncs the "~30 minutes" session-length wording in contributing.qmd/README.md to "~30-40 minutes," matching what AGENTS.md now states.
Points write-up.qmd at AGENTS.md for the fuller rationale.

Checklist

Preview locally with quarto preview - no errors or warnings
Added any non-standard assets to .github/_quarto.yml ignore list (if needed) — n/a, no new assets

## Description Adds `AGENTS.md` at the repo root: a single instruction set any coding agent can use to write or review a walkthrough post, covering repo conventions (post structure, frontmatter, `draft: true`, branch naming) plus a 15-item review checklist grounded in cognitive load theory, the Diátaxis framework, Mayer's multimedia learning principles, Carroll's minimalism, and related literature. Every citation was checked against the source to confirm it actually supports the claim next to it, not just asserted. Also: - Adds the `draft: true` convention and the post-independence rule to `write-up.qmd`. - Syncs the "~30 minutes" session-length wording in `contributing.qmd`/`README.md` to "~30-40 minutes," matching what `AGENTS.md` now states. - Points `write-up.qmd` at `AGENTS.md` for the fuller rationale. ## Checklist - [x] Preview locally with `quarto preview` - no errors or warnings - [ ] Added any non-standard assets to `.github/_quarto.yml` ignore list (if needed) — n/a, no new assets

LucileSol (Migrated from github.com) reviewed

2026-08-24 13:37:24 +00:00

github-actions[bot] commented

2026-08-24 13:38:24 +00:00

(Migrated from github.com)

PR Preview Action v1.8.1
Preview removed because the pull request was closed.
2026-09-01 19:27 UTC

[PR Preview Action](https://github.com/rossjrw/pr-preview-action) v1.8.1 :---: Preview removed because the pull request was closed. 2026-09-01 19:27 UTC

CormacKinsella (Migrated from github.com) approved these changes

2026-08-27 09:34:24 +00:00

mahesh-panchal commented

2026-08-27 11:32:51 +00:00

(Migrated from github.com)

So, I just used the AGENTS.md to review Cormacs PR, and now I'm wondering about it's use.

It's useful, but the extra readability principles can significantly restructure a post.

So, I just used the AGENTS.md to review Cormacs PR, and now I'm wondering about it's use. It's useful, but the extra readability principles can significantly restructure a post.