# Recommended ways of working (by phase)

PM on Rails is built on the premise that "anything people don't have to do is handed off to AI and automation". Below is an example of how to use it phase by phase, together with **which manual work disappears**. Adjust it to the way your team works.

There is one important premise: this is **a loop, not a one-way schedule**. Requests change with every meeting, defects turn up with every round of testing, and those feed back into requests and requirements as material for the next lap. PM on Rails is built so that this "coming back" can be treated as normal operation rather than an accident.

```mermaid
flowchart LR
  A["Collect (meeting notes, documents)"] --> B["Requirement cards"]
  B --> C["Confirm scope"]
  C --> D["Stories and scenarios"]
  D --> E["Implementation (tasks, PRs)"]
  E --> F["Testing"]
  F -->|reflect defects in the spec| B
  A -->|next meeting| B
```

## The rhythm is the same in every phase

You don't need to learn how to use each screen separately. In PM on Rails, work runs on much the same three beats whatever the phase.

1. **Put material in** — meeting notes, documents, recordings, conversation.
2. **AI produces a first draft** — requirement cards, stories and scenarios, review findings, design document drafts, estimates.
3. **A person checks it and commits** — choose "new / update / skip", edit and save, approve.

Four shared properties support this rhythm.

- **AI never commits anything on its own.** Everything generated is a proposal or a draft, and a person always chooses whether to import it.
- **Slow generation runs [in the background](https://pmonrails.com/en/docs/jobs.md).** You can carry on with other work while it runs.
- **Once development starts, progress advances automatically along with the work.** There is no job of going around updating states by hand (a pull request merged into the default branch completes a task; sprints advance by date).
- **When something changes, badges and notifications come to you.** You don't have to go looking for changes.

## The entry points are not only the screens

You can reach the same graph from whichever entry point suits your position and situation. **Whichever one you work from, the same data is updated and the same permissions and the same business rules apply.**

| Entry point | When it fits |
| --- | --- |
| The screens (UI) | Agreeing with the stakeholder while looking at the screen together; getting an overview from the roadmap and the board |
| [In-app AI assistant](https://pmonrails.com/en/docs/ai-assistant.md) | The entry point after login. Attach documents and organise and check in conversation: "what's the progress?", "summarise this request" |
| The AI chat on the right (every screen) | Asking and instructing while looking at a screen, pointing at "this screen" or "this story". The conversation continues per project |
| Connector for Claude (Web / desktop) | A PM getting everyday management done from chat without opening the screens: filing requests, changing priorities, checking progress |
| [Claude Code / Codex](https://pmonrails.com/en/docs/ai-coding.md) | An engineer reading and writing tasks and scenarios from inside the implementation work |

Connecting the Claude connector only takes signing in to PM on Rails and approving the consent screen at connection time (it can only act within the permissions you approved).

## Requirements definition phase (PM x stakeholder) — no more transcribing and re-gathering

Repeat the same three steps after every meeting.

1. **Collect** — create or import meeting notes and documents in [knowledge](https://pmonrails.com/en/docs/knowledge.md). Add recordings through “Import video/audio” to transcribe them automatically.
2. **Turn it into requirement cards** — generate [requirement cards](https://pmonrails.com/en/docs/demands.md) in bulk, per folder or across the whole project. The results line up in a review panel, and you import them by choosing "create new / update existing / skip". They arrive with MoSCoW, the 5 Whys, latent needs and estimated value already attached, so **there is no step where anyone writes a document from zero — people only correct**.
3. **Agree with the stakeholder** — look at the [Confirm scope](https://pmonrails.com/en/docs/scope.md) screen together, drag the cards, and settle "must / should / could / won't". The panel on the right lets you adjust the three human judgement axes (business importance, ease of acceptance, ease of implementation), and **cards where the AI's priority and the human judgement diverge become the flag for "cards worth discussing"**. The agreement flows straight downstream, so digging up meeting notes later disappears.

Being explicit about "won't" automatically puts the requirements created from that request out of scope too. This single move does the most to prevent misaligned expectations.

## Design phase (PM → engineer) — don't write drafts from a blank page

- From the settled requests, generate [user stories and scenarios](https://pmonrails.com/en/docs/stories.md) in bulk (1 to 5 per request). If the direction is wrong, you can regenerate all of them.
- Because scenarios take the form "in this situation, if you do this, this happens", they are **a definition of done the stakeholder can read and confirm**. Agreeing here stops the "is it done or not" argument flaring up later.
- Before work starts, use the [AI review of requirements](https://pmonrails.com/en/docs/stories.md) to mechanically surface contradictions, gaps, ambiguity and technical points to check (how questions and answers go round is the next section).
- Build the [design docs (API design, DB design)](https://pmonrails.com/en/docs/basic-design.md) that implementation stands on, with AI first drafts and mermaid diagrams. No more time spent facing a blank page.
- Put adoption decisions and design decisions into [decision records](https://pmonrails.com/en/docs/decisions.md). Fewer meetings spent trying to remember "why did we do it this way?".

## Questions for stakeholders, and reflecting the answers

The back-and-forth of "which way should this be?" that always comes up while you firm up requirements is designed to run on Slack messages and approvals alone.

1. **AI compiles the questions** — findings from the [AI review of requirements](https://pmonrails.com/en/docs/stories.md) come with **question text you can send to the stakeholder as it is**. A finding can be kept as a question linked to a requirement, so the list of things to ask — the questionnaire — collects across the project under [open questions](https://pmonrails.com/en/docs/clarifications.md). You don't keep track of what you forgot to ask in your head.
2. **You can pick where it goes when you send to Slack** — if Slack integration is set up, "Share to Slack" on an open question lets you pick the destination from the Agent / shared channels or the notification channels registered on the project. Once shared, it is pinned to that Slack thread and later replies are imported from the same thread (sharing requires viewer or above; viewers are shown only the Agent / shared channels and are never told that notification channels exist. "Copy questions in bulk" and pasting into an email works too). Your client doesn't have to learn a new tool.
3. **The Slack bot can expand open questions** — in a Slack channel tied to a project, mention `@pm-on-rails` with the Japanese open-questions keyword to list the unresolved open questions. Mention `@pm-on-rails` with that keyword plus the Japanese word for "expand" and it posts the open questions that have not been shared into that channel. The bot decides which project it is dealing with from the channel the message was written in, and never expands into channels that are not registered.
4. **Slack replies stay as a discussion log** — when the other side replies in the thread of a shared question, the content is imported as a child comment in PM on Rails. Because an answer sometimes comes together mid-discussion, a message is not promoted to a formal answer on its own; it is kept as a conversation log. Only replies from members who can view the project, using the same email address or an explicitly linked Slack account, are imported. What you send back from the screen also reaches the same thread, so the conversation looks the same whether you read it in Slack or in PM on Rails.
5. **You can build an agenda of open items** — feed the unanswered and under-discussion questions left in open questions to the AI assistant or to Claude Web over MCP, and you get a Markdown agenda for the next meeting straight away. Group similar questions and lay out what you want to decide, your recommended option and the wording to ask the other side, and it is ready to take into the meeting. Save the Markdown you produced as a document in [knowledge](https://pmonrails.com/en/docs/knowledge.md) and later AI runs can cite it as evidence too.
6. **Answers return to the spec** — once an answer comes in and the question is resolved, AI prepares **update proposals** for the requirements, stories and scenarios based on that answer (they are rebuilt if the answer changes). Slack replies stay as a discussion log, so record the settled answer in the answer field before resolving. The proposals **wait for approval**: the spec does not change until you apply them one by one, or all at once with "Apply all", under "Update proposals awaiting approval" on the Open questions screen. When you are in a hurry, "Create update proposal" on a question creates one right away. No transcribing, and nothing left untranscribed.

The whole chain of "compile the questions in a spreadsheet, get the answers, hand-edit the requirements document, then hunt for the edits you missed" is replaced by **Slack messages and approvals**.

## Planning phase (PM x engineer)

Once you know what you are building, you carve up "when and how much".

![PM on Rails roadmap. Cycle or quarterly plans and the chunk being built now. Before: you asked when it would land. After: you can follow the current place yourself.](https://pmonrails.com/docs-img/roadmap.png)

- **Lay it out on the roadmap** — drag epic bars to place the broad "what ships when" ([Making progress visible](https://pmonrails.com/en/docs/progress.md)).
- **Cut a sprint** — create a sprint by **specifying only the period (start and end date)**, at a length that suits your team such as one or two weeks. The state (preparing → in progress → done) advances automatically from the dates, so there is nothing to switch.
- **Assign what you are doing this round** — assign the stories and tasks to get through in that sprint. What you decide here becomes "this round's promise" and the baseline for the burndown and member load. The board is filtered to "the current sprint" by default, so what you look at day to day is just this round's promise.
- **AI fills in first-draft estimates automatically** — so you never end up unable to read progress because fields were left blank (the final call stays with people).
- **Avoid over-filling** — the amount assigned against each member's capacity x utilisation rate is colour-coded, and overload (too much in the sprint) is the cue to revisit the allocation.
- **Leftovers move on automatically** — when a sprint with carry-over enabled finishes, unfinished tasks move to the next sprint automatically. The pace at which past sprints were burned down (velocity) also gives you a guide for how much you can take on next.

## Implementation phase (engineer) — no more spec briefings and progress entry

The experience we are aiming for is that **engineers barely need to open the PM on Rails screens**. You work in conversation from [Claude Code / Codex](https://pmonrails.com/en/docs/ai-coding.md).

1. "Show me the unstarted tasks in the current sprint" — a list comes back.
2. "What's the background and the acceptance conditions for this task?" — request → requirement → story → scenario comes back **with the connections**. You no longer have to produce material that re-explains the spec.
3. When you start, the response includes **the branch name and the one line to paste into the pull request body**. Use them as they are and the task and the pull request are linked ([GitHub integration](https://pmonrails.com/en/docs/github.md)).
4. When the pull request is merged into the default branch (main), the task automatically becomes "done" and the parent story's state is recalculated. A merge into a feature branch is recorded as "waiting", and the task completes once that branch reaches main. No progress entry, and nobody chasing you for it.

### Why AI agents can build things that actually fit

The accuracy of a coding agent is decided by **the quality of the context it is handed**. That is exactly where PM on Rails works.

- **Because the background comes with it** — the agent receives not the task on its own but the whole chain of request → requirement → story → scenario. Implementation starts with "why we are building this" and "what done looks like" already known, so there is less code written on assumptions and less going back to ask the PM.
- **Because the definition of done is machine readable** — scenarios take the form "in this situation, if you do this, this happens", so an agent can use them directly as the basis for tests.
- **Because there is no reporting work** — starting work, linking the pull request and completing all connect automatically within the flow of implementation, so neither the agent nor a person performs an action purely to report progress.
- **Because you notice changes mid-flight** — even if the PM changes the spec while you are implementing, "upstream changed after I started" is detected. It prevents the accident of building all the way through against an old spec.
- **Because handing work over doesn't break things** — the same permissions, business rules and safety checks that apply on screen also apply to what the agent does.

Seen from the PM side, **[the board and the burndown](https://pmonrails.com/en/docs/progress.md) move even though nobody is updating states by hand**. Overdue and abandoned tasks are detected automatically every morning and their assignees are notified. The time spent going round asking "how far have you got?" in a progress check-in disappears.

## Testing phase — no rethinking "what should we check?"

- Scenarios are the check items as they stand, so you don't raise test viewpoints separately.
- On the [Tests](https://pmonrails.com/en/docs/test-results.md) screen, record the result per scenario (pass / fail / skip). Importing from the development side (CI and so on) is supported too.
- From a failed scenario you can **file a bug** on the spot and run it through the same board as any other task.
- With coverage and pass counts, you can check "how much is really finished" in one continuous line from the request.

## Bug fixing and rework phase

Even after a defect is found, you can manage it in one continuous line from the request.

1. **File the bug** — file it as a "defect (bug)" task and record the severity and the **impact (which scenarios and requirements it hits)**.
2. **Work it on the board** — progress it on the same board as other tasks. There is no separate dedicated screen.
3. **Record the resolution** — leave the classification ("fixed / won't fix / duplicate / cannot reproduce") and the reason.
4. **Prevention goes into requirements** — if it "should be fixed as a spec", raise a new request or requirement from the bug ([Bugs and change management](https://pmonrails.com/en/docs/bugs-changes.md)).
5. **Update the spec with a change request** — propose a change to a requirement or a scenario, approve and apply it to generate a new version, record the regression passes with their grounds, and confirm the merge; **related bugs are closed automatically**.

Because "bug → resolution → prevention as a requirement → change request → retest" is connected and goes round, what you fixed doesn't vanish as an ad-hoc patch; it stays as material for the next improvement.

## After a check-in, or when the spec changes — no manual impact tracking and catch-up

When the next meeting comes, you go back to the same three steps as the requirements definition phase. What differs is the behaviour from the second round on.

- **Proposals come with a diff against existing cards** — [diff check](https://pmonrails.com/en/docs/change-tracking.md) matches the requests extracted from new meeting notes against existing cards by meaning. It never merges on its own: it presents the candidates newest-first with a diff of "which fields change how", so you just pick and apply. Nobody eyeballs the two versions to spot what changed. The more meetings you hold, the more the cards **grow** rather than pile up.
- **Downstream notices automatically** — when you update a request or a requirement the change is recorded, and the user stories screen shows it as "unacknowledged upstream changes" with a count. You can check what changed (before and after) and which stories and scenarios are affected, and acknowledgement is tracked per person (someone else acknowledging doesn't clear yours). On top of that, **AI prepares proposed updates for downstream (requirements, stories, scenarios) automatically**, so catching up takes only an approval. Tasks whose upstream changed after work started are marked "needs re-checking" when the pull request is merged.
- **Notifications reach the people involved** — through the in-app bell, email and the every-morning digest ([Notifications and Slack](https://pmonrails.com/en/docs/notifications.md)).
- **Big spec changes go into a new version** — requirements and scenarios switch to a new version instead of being overwritten, and the old version stays as history. "Implementation carries on while nobody notices something changed" doesn't happen.

## Using it together with contractors and clients

- Contractors who do the work are invited as **editor**. They can move the board and tasks directly.
- Clients and the business side are invited as **viewer (read-only by default)**. They can review requirement cards, scope decisions, and the roadmap, then append comments, acceptance-test results, and bug reports linked to an acceptance scenario ([Members and permissions](https://pmonrails.com/en/docs/members.md)).

> This is an example of how to operate, in line with functionality you can verify in the code.

---

https://pmonrails.com/en/docs/workflow