docs: restructure README around the user journey - #238
Open
omaiesh wants to merge 13 commits into
Open
Conversation
github-actions
Bot
added
the
documentation
Contributor
Rosetta Triage ReviewSummary: Reorders the README around what a reader does (decide → install → initialize → run a workflow) instead of leading with positioning content, folds Findings:
Caveats:
Automated triage by Rosetta agent |
omaiesh
force-pushed
the
docs/readme-user-journey-216
branch
8 times, most recently
from
August 9, 2026 18:29
7bde800 to
020dce9
Compare
Reorder the README so a reader reaches something actionable immediately instead of scrolling past positioning material. - Lead with what Rosetta changes about the agent's behaviour, then a "Do you need it?" block so the decision to continue or stop happens before install. The intro video is collapsed, inline. - Quick start: four numbered steps (install, initialize, review and commit the generated context, run your first workflow). Per-IDE install is one table. Committing the generated files is now its own step rather than an aside. - Add "The recommended path": the five steps of a real task (context -> pin down what to build -> implement -> test -> check before ship), each with the workflows that fit and example prompts, and two recordings of it on real projects. Covers all 14 active workflows; previously only 7 were listed. - Add "What's inside: the skill library" covering the R3 core skills, including the always-on set that backs each guardrail. - Replace the routing table with "Go deeper": one collapsed table of every document and what it is for, including FAQ, ELEVATOR_PITCH, REVIEW, docs/CONTEXT, docs/MCP-ARCHITECTURE and llms-full.txt, none of which were linked before. - Drop the positioning material (comparison tables, layering diagram, "why not IDE rules", the 12-point collapsible) and the Contributing section. That ground is covered by OVERVIEW.md and docs/CONTEXT.md, both linked from Go deeper. CONFIGURATION.md is cleaned up to match, since the README now sends readers there for workspace setup: - Remove the "Install and Onboard" section and every Quick Start reference. Installing and initializing are covered before a reader reaches this page, and repeating them here is how the two drifted. - Renumber the remaining sections and add a short overview list of the five setup steps, so the page opens with what it actually asks of you. QUICKSTART.md is left untouched. The README now carries the same happy path inline, so the two overlap; that is recorded in the PR description rather than resolved here. Closes #216 Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
omaiesh
force-pushed
the
docs/readme-user-journey-216
branch
from
August 9, 2026 20:38
020dce9 to
01cf34c
Compare
YevheniiaLementova
previously approved these changes
Aug 10, 2026
YevheniiaLementova
left a comment
YevheniiaLementova
left a comment
Contributor
There was a problem hiding this comment.
I've left several suggestions, otherwise LGTM!
isolomatov-gd
requested changes
Aug 10, 2026
Contributor
There was a problem hiding this comment.
This is definitely a step in the right direction, but it is just rephrasing what we had. We need genuinely new good README.md as we talked with important notes on what/why rosetta does something really better.
Example: Discovery phase in coding-flow finds genuine issues and artifacts, design phases allows to select one of three best designs, makes AI follow your intent, etc.
Replace the walkthrough-style README with a shorter version that routes instead of explaining: install in three numbered steps with a recognizable success signal, four "why this exists" sections written as problems, and a workflow reference grouped by intent. - Drop the publish-rosetta-mcp and publish-rosetta-cli CI badges - Move /init-workspace-flow out of the reference tables: it is a precondition, not one of the "what I want to do" choices, so it now sits under the axis statement and links back to Install - Rename "Set up, and when you are stuck" to "When you are stuck" Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Restore CONFIGURATION.md to its state on main. The README restructure had renumbered its sections and removed the Quick Start pointers next to each "Initialize Rosetta" action; that is a separate concern and belongs in its own PR, per CONTRIBUTING's one-concern-per-PR rule. This also restores the token-saving tip, which had been deleted here on the grounds that the README quick start carried it. The rewritten README does not carry it, so it currently exists nowhere. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
omaiesh
force-pushed
the
docs/readme-user-journey-216
branch
from
August 11, 2026 20:52
9315d7d to
0fdab6d
Compare
Wrap the documentation index in <details> so it does not compete with the install and reference sections, and list every document instead of a subset. Adds PLUGINS.md, MCPs.md, INSTALLATION.md, ELEVATOR_PITCH.md, CHANGELOG.md, REVIEW.md, docs/CONTEXT.md and docs/mcp/DEPLOYMENT_GUIDE.md, taking coverage of root-level docs from 10 of 15 to 15 of 15. Rows are ordered by where the reader is: install, configure, use, understand, recover, build on it, contribute, security. Drops the trailing "Not here:" sentence, which listed directories rather than answering a reader's question and mixed instruction sources with working material already covered by DEVELOPER_GUIDE.md. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Only README.md overlapped: main changed 252 files, this branch 1. main's README edits and this branch's rewrite could not be merged line by line, because the branch replaces the file wholesale. Resolved by keeping the rewritten README and composing in main's actual contribution, the new 20-file user-guide/: - a pointer to the User Guide after the install steps, where a new reader asks "now what?" - a row in the documentation table - USAGE_GUIDE.md's row reworded to "the full reference, every workflow phase by phase", so it no longer competes with the User Guide for the "day to day" slot that main's own table gave to user-guide/ Verified after the merge: 53 markdown files, 451 relative links and 114 anchors resolve, 0 broken. The user-guide/ links to README.md#scenarios-at-a-glance are relative to user-guide/ and resolve to its own README, not the root one. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
| **1. Install the plugin.** Files install locally — no server, no live connection at request time. Install for **one** agent only: two installations leave you with duplicate tools, commands and context, which is worse than not installing at all. | ||
|
|
||
| **Teach agents how to think, not what to do.** The model already knows Python and React; what it lacks is your engineering discipline. That's what Rosetta encodes. | ||
| <details> |
Contributor
There was a problem hiding this comment.
We should not have those details here - again over explaining.
Only high-level + links.
All text MUST follow ASD-STE100 Simplified Technical English.
## 1. Install
<one sentence>
- Plugin (links)
- MCP (links)
## 2. Onboard (required)
<one sentence - what and why>
- Link
## 3. Configure Ecosystem (optional - recommended)
<one sentence - what and why>
- Link
## 4. All-In-One Workflows
<sentence - what and why>
### 4.1 Help Workflow
<sentence - what and why>
- Link
### 4.2 Coding Workflow
<sentence - what and why>
- Link
### 4.3 API AQA Workflow
<sentence - what and why>
- Link
etc.
What means what it does (example: coding flow executes: discovery, design, specifications, implementation, review, unit/integration/e2e testing, final manual validation)
Why means reasoning when/how to use it but not directly saying so (example, appended to previous: Covers E2E and gives fully implemented and tested solution, intended to be used with medium to large tasks.
Final worked example for coding flow:
## 4. All-In-One Workflows
Those are implemented to fully cover entire area of work as All-In-One.
If full workflow is not needed you can ask or use skills directly.
...
### 4.2 Coding Workflow
Orchestrates subagents and executes: discovery, design, specifications, hitl, implementation, review, unit/integration/e2e testing, final manual validation by AI.
Covers E2E and gives fully implemented and tested solution, intended to be used with medium to large tasks.
[Coding User Guide](user-guide/scenarios/coding.md) · [Coding Workflow Details](https://griddynamics.github.io/rosetta/docs/coding-flow/)
...
Contributor
There was a problem hiding this comment.
And the first thing I see details+summary.
Again it is not implemented as written above.
Contributor
There was a problem hiding this comment.
My suggested structure also is just a list, it should be grouped into: getting started with help, coding, quality engineering (QE), requirements/specs & hitl, modernization, etc.
…esolve reviewer feedback Brings back per-scenario init commands (brownfield/greenfield/composite) directly in the README instead of a single link out, drops the standalone Configure Ecosystem and Working on Rosetta itself sections, and normalizes every Documentation table entry to a consistent bare-filename style with descriptions grounded in each doc's own "Who is this for?" line. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
isolomatov-gd
requested changes
Aug 20, 2026
isolomatov-gd
left a comment
isolomatov-gd
left a comment
Contributor
There was a problem hiding this comment.
My comment is not resolved actually
…ource Restructures Install/Onboard/Configure Ecosystem/Workflows per isolomatov-gd's repeated review feedback: drops all <details> blocks, groups the 13 workflows into categories with What/Why plus a Skills line per entry, and rewrites the Skills section down to a one-line pointer at the full catalog now that each workflow lists its own. Every skill attributed to a workflow is grepped from that workflow's own source file (main + phase files), fixing an earlier bug where comma-separated "USE SKILL `a`, `b`, `c`" lines only registered the first name. Also restores hitl and data-collection where they were dropped inconsistently during curation, and trims the Coding Agents Prompting entry to its one distinctive skill instead of padding with the generic baseline trio. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
…fixes Removes the six category divider headings under All-In-One Workflows after settling on a size (## then #### then ## again) that kept conflicting with either the section's own heading or its child ### 4.x entries -- a flat list matches the reviewer's original template exactly and avoids the ambiguity. Reorders the 13 entries: Code Analysis and Ad-hoc move up to 4.3/4.4, the QE cluster (Test Case Generation, API AQA, UI AQA) follows as 4.5-4.7, then Requirements Authoring at 4.8. Also bumps the skill count callout to "40+". Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
…ay-to-day work Restores the "AI coding agents are great" opening over the shorter "impressive on their own" version. Rewrites the Skills section pointer to name coding, qa-knowledge, and testing instead of the internal guardrail skills, since those are what a regular engineer recognizes day to day; drops the now-inaccurate "guardrails on every task" framing that didn't fit this example set. Bolds the "teach agents how to think" line. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Contributor
|
This message from the comment was not resolved:
|
| Use it when you do not know what Rosetta can do, or which workflow fits. | ||
|
|
||
| ## Without Rosetta / With Rosetta | ||
| **Skills:** [`/natural-writing`](instructions/r3/core/skills/natural-writing/SKILL.md), [`/reasoning`](instructions/r3/core/skills/reasoning/SKILL.md) |
Contributor
There was a problem hiding this comment.
What skills lis here for? Does it bring value or overwhelms the first time reader? Also what pointing to SKILL.md file achieves?
| Reverse-engineers a codebase into architecture documentation. Every claim traces to real code. | ||
|
|
||
| Higher layers propagate to every project automatically; teams customize without forking. Everything is authored in markdown and versioned in Git. | ||
| Use it to understand a system before you plan, refactor, or migrate it. |
Contributor
There was a problem hiding this comment.
And here is a failure.
Look how example for coding flow was provided and how this one does. First of all lie about architecture documentation (too narrow scoped to architecture documentation also it is NOT ONLY reverse engineering), third sentence repeats what first do (useless tautology).
### 4.2 Coding Workflow
Orchestrates subagents and executes: discovery, design, specifications, hitl, implementation, review, unit/integration/e2e testing, final manual validation by AI.
Covers E2E and gives fully implemented and tested solution, intended to be used with medium to large tasks.
[Coding User Guide](user-guide/scenarios/coding.md) · [Coding Workflow Details](https://griddynamics.github.io/rosetta/docs/coding-flow/)
Replace the per-workflow 4.x sections with scenario tables grouped by intent, so a reader picks a workflow by what they want to do. Rewrite the "What it does" column for all 13 workflows: each entry now states the workflow's operating logic and its essential engineering activities — human approval gates, independent agent review, subagent delegation — instead of listing phases in order. Wording is grounded in the phase definitions under instructions/r3/core/workflows/. Condense the intro to a single positioning sentence and drop the separate Skills section, since workflows are the entry point. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Conflict in README.md: main reworded a cell in the "Why use it" table, which this branch removes along with the other positioning sections (comparison tables, layering legend, "Why not just use IDE rules?", the 12-point collapsible, Contributing). Kept the branch's restructure — that ground is covered by OVERVIEW.md and docs/CONTEXT.md, both linked from the Documentation table. No other README changes landed on main since the merge base. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes #216.
Two files:
README.md(the restructure) andCONFIGURATION.md(cleanup, because the README now sends readers there).README
It opened with positioning material — hero video, "What is Rosetta", a layering diagram, comparison tables, a 12-point collapsible — before a reader reached anything they could act on. This reorders it around what a reader actually does: decide whether they need it, install it, run something.
Intro — what Rosetta changes about the agent's behaviour, then a
Do you need it?block with five concrete symptoms, so the stop-or-continue decision happens before install rather than after scrolling. The intro video is collapsed, inline.Quick start — four numbered steps: install, initialize, review and commit the generated context, run your first workflow. Per-IDE install is one table. Committing the generated files is now its own step; previously it was one clause inside a paragraph, and it is the step people skip.
The recommended path — new section covering the five steps of a real task: get context → pin down what to build → implement → test → check before it ships. Each lists the workflows that fit, with example prompts, and the section ends with two recordings of the path on real projects. All 14 active workflows are represented; the old
Top Workflowslist had 7 and omittedmodernization-flow,research-flow,adhoc-flow,external-lib-flow, andcoding-agents-prompting-flow.What's inside: the skill library — the R3 core skills grouped by purpose, including an
Always activegroup that names the skill behind each guardrail. The oldTop Guardrailslist described behaviours without saying where they came from.Go deeper — one collapsed table of every document and what it is for. Adds
FAQ.md,ELEVATOR_PITCH.md,REVIEW.md,docs/CONTEXT.md,docs/MCP-ARCHITECTURE.md, andllms-full.txt, none of which were linked from the README before.Removed — the comparison tables, the layering diagram, "Why not just use IDE rules?", "Who benefits", the 12-point collapsible, and the
Contributingsection. That ground is covered byOVERVIEW.mdanddocs/CONTEXT.md, both linked from Go deeper.CONFIGURATION.md
The README now points here as the thing to do before real work, so the page had to stop repeating what precedes it.
Install and Onboardsection is removed, along with all fiveQuick Startreferences. Installing and initializing happen before a reader gets here; carrying a second copy of those steps is how the two documents drifted apart in the first place.Set Up the Repository→ 1,Choose a Workspace Layout→ 2,Modernization Additional Setup→ 3), and the internal link to the modernization section updated.No existing wording was rewritten — only removed, renumbered, or linked.
Known overlap, deliberately not addressed here
The issue offered two options for QUICKSTART. This PR takes neither —
QUICKSTART.mdis untouched. The README now carries the same happy path inline, so both documents describe install and first-run.docs/reviews/DOC-STRUCTURE-PLAN.mdis also untouched, so its README contract (which lists "full install steps" and "workflow how-tos" underExcludes) and its open items §5.1 and §5.4 still read as they did before this PR. Both were flagged in the triage comment on #216.Reconciling the plan and deciding QUICKSTART's fate is follow-up work.
Review notes
SECURITY.md; workflow descriptions come frominstructions/r3/core/workflows/; the skill list matchesinstructions/r3/core/skills/.git addline in step 3 uses a<placeholder>rather than an enumerated file list, since the canonical committed-vs-excluded list lives inINSTALLATION.mdand would drift if copied.PLUGINS.md,MCPs.md,INSTALLATION.md,QUICKSTART.md, and thedocs/web/mirrors.docs/web/mirrors of these pages are not updated here.🤖 Generated with Claude Code