Skip to content

Docs pass: update docs/ site for the prompt-driven harness (post #37) #38

Description

@samkeen

Context

PR #37 refactored Tilth to a prompt-driven core (evaluator-only gate; features authored as markdown under <repo>/.tilth/tasks/ instead of an interview-generated prd.json; no prep-feature, no codified ruff/pytest validators, no self-improve step). The README was fully rewritten in that PR and is the current source of truth for the run flow. The docs/ site was intentionally deferred — it still describes the old two-step prep-featurerun flow with validators, prd.json, seed-meta, and self-improve.

This issue tracks bringing docs/ back in line. Approach: diff-driven — work from #37's commits (b431215, e57b0ea, a5496e2) and the rewritten README, page by page.

Structural changes

  • Delete docs/deep-dives/seeding.md — the prep-feature interview engine it documents is gone.
  • Replace docs/deep-dives/prd-json.md with a .tilth/tasks/ format page (frontmatter id/title + ## Description / ## Acceptance criteria; overview.md; harness-owned task-status.json). See tilth/tasks.py.
  • mkdocs.yml nav — drop the seeding.md entry, rename/repoint the prd-json.md entry, and refresh the annotated nav comments that mention prep-feature/validators. Keep mkdocs build --strict green.
  • Dead linkrunning-the-demo.md links to examples/seed-reference/ (deleted in Prompt-driven harness: drop codified validators, prep-feature, and self-improve #37). It's an external GitHub URL so --strict won't flag it, but the link is dead.

Page rewrites (by amount of stale content)

Heavy (the prep-feature/validator narrative is the backbone):

  • getting-started/running-the-demo.md — two-step flow → .tilth/tasks/ + tilth run; drop validators/self-improve from the per-task lifecycle.
  • getting-started/your-own-project.md — drop prep-feature seeding; author .tilth/tasks/.
  • deep-dives/two-loops.md — remove the validator step from the inner loop.
  • architecture/memory-channels.md — drop prd.json/seed-meta; add task-markdown (overview.md + tasks) + task-status.json.
  • architecture/anatomy-of-a-run.md — remove validators/self-improve from the data-flow.
  • deep-dives/worker-evaluator-dialogue.md — evaluator is the only gate; drop "validators passed" framing.
  • deep-dives/agent-visibility.md — update the visibility table.
  • architecture/overview.md — invariants/repo-layout (no validators.py, no seed/).
  • deep-dives/session-layout.mdprd.jsontask-status.json; tasks now live in the repo's .tilth/tasks/.

Light:

  • index.md, getting-started/installation.md (drop TILTH_PREP_*), getting-started/visualizing.md, getting-started/resuming.md, deep-dives/{resume-mechanics,hyper-observability,token-recording,index,reset-mechanics,caps}.md.

Diagrams to regenerate (via docs/assets/IMAGE_STYLE.md)

The README's two images (brain-hands-session.png, session-render.png) are still accurate. These four are not:

Image Page Fix
harness-loop.jpg index.md drop the validators box + "Fails" path; flow is task → worker → evaluator → commit, only "Rejects" remains
per-task-lifecycle.jpg running-the-demo.md 6 boxes → 4 (Prompt, Tool Loop, Evaluator, Commit); remove VALIDATORS + SELF-IMPROVE and the validator_failed feedback curve
session-end.jpg running-the-demo.md drop proposed-learnings.md; artifacts are events.jsonl, summary.json, checkpoint.json, task-status.json
session-layout.png running-the-demo.md, session-layout.md prd.jsontask-status.json; tasks live in the repo's .tilth/tasks/, not under sessions/<id>/

Done when

uv run --extra docs mkdocs build --strict is green, no page references prep-feature / prd.json / codified validators / self-improve as current behaviour, and the four diagrams are regenerated.

Refs #37.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions