Skip to content

Update docs for recent features and simplify README#103

Merged
sebastientaggart merged 1 commit into
devfrom
feature/update-docs-simplify-readme
Apr 11, 2026
Merged

Update docs for recent features and simplify README#103
sebastientaggart merged 1 commit into
devfrom
feature/update-docs-simplify-readme

Conversation

@sebastientaggart

Copy link
Copy Markdown
Member

Update skill documentation to cover features added in recent PRs and simplify the README into a focused marketing page for first-time visitors.

Skill docs updates:

  • docs/skills/start.md: Added structured issue body sections (Problem to Fix, Why it Matters, General Approach, Complexity, Acceptance Criteria), intent classification for human gates, and complexity scale guidance
  • docs/skills/submit-for-review.md: Added post-review human gate for non-blocking findings and resolution comment step after merge
  • docs/index.md: Added /submit-for-review to the human gates list

README simplification (126 → 77 lines, -39%):

  • Tightened opening pitch, names all four supported agents
  • Replaced verbose skill list with a compact table
  • Removed GitHub baseline setup section and reviewer selection details (belong in docs, not landing page)
  • Trimmed philosophy to three focused paragraphs
  • Simplified quick start to the three essential commands
  • Collapsed skill reference into a single linked line

Issue #102

@sebastientaggart

Copy link
Copy Markdown
Member Author

Review Summary

Verdict: APPROVE

Findings

  • [NOTE] The README quick start drops git submodule update --init after git submodule add, which is technically not needed immediately after add (it clones inline), but new users following the three-line recipe on a fresh clone of their own repo later will need it. The full quickstart in docs/index.md does include this step, so no gap in practice — just flagging the tradeoff.
  • [NOTE] The "GitHub baseline for PM/BA setup" section (starter labels, QA lifecycle labels, milestone guidance) and the "Reviewer selection is never automatic" paragraph were removed from the README and do not appear verbatim in any docs page. The label/reviewer details are covered in the individual skill doc pages (docs/skills/start.md label resolution, docs/skills/submit-for-review.md reviewer selection), so the information is reachable — but there is no single "setup checklist for PMs" page anymore. If that audience matters, a future docs page could fill the gap.
  • [NOTE] The "Agent-agnostic" philosophy bullet was removed. The concept is implicit in the architecture description ("Write once... sync to Claude Code, Cursor, Gemini, and Codex") but is no longer called out as an explicit design principle. Minor loss of emphasis only.

Correctness check

All doc updates accurately reflect the source skill files:

  • Structured issue body (5 sections: Problem to Fix, Why it Matters, General Approach, Complexity, Acceptance Criteria) matches skills/start.md lines 158-179.
  • Complexity indicator (trivial/moderate/significant/extensive with one-line justification) matches skills/start.md lines 170-171, 181-185.
  • Intent classification (4 categories for human gate) matches skills/start.md lines 130-135 and 280-284.
  • Post-review human gate for non-blocking findings matches skills/submit-for-review.md lines 207-224.
  • Resolution comment on linked issue matches skills/submit-for-review.md lines 248-267.
  • docs/index.md human gates list now correctly includes /submit-for-review.

Link check

All markdown links resolve to existing files: docs/index.md, docs/branching.md, docs/customization.md, docs/config-reference.md, docs/adapters.md, all seven docs/skills/*.md files, and .github/assets/readme-inline-agents-working-with-humans.png.

No issues found that would block merge. The skill doc updates are accurate and complete, the README simplification is clean, and no critical information was lost without coverage elsewhere.

@sebastientaggart
sebastientaggart merged commit 6853a90 into dev Apr 11, 2026
2 checks passed
@sebastientaggart
sebastientaggart deleted the feature/update-docs-simplify-readme branch April 11, 2026 14:18
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant