# AI assistant (prompt reference)

It helps you organise and update things in conversation, informed by your project's information (for how it works, see [How the AI works](https://pmonrails.com/en/docs/graphrag.md)). Talk to it using phrasings like the ones below.

![PM on Rails AI assistant. Conversation and the next step are visible; requirement cards, questions and tasks are created only after you approve a confirmation card. Before: you re-read documents and picked out open questions by hand. After: review and run, and organisation starts.](https://pmonrails.com/docs-img/chat.png)

Use "Attach documents" to add meeting notes or an RFP, then ask AI to turn them into requirement cards. Supported formats are Markdown (.md / .markdown), text (.txt), Word (.docx) and Excel (.xlsx), up to 20 MB per file. Selecting a file saves it to the project's Knowledge. Word and Excel files are converted to text; originals are not stored. Removing an attachment keeps the saved document in Knowledge.

The "Review list" lets you select up to five requirements at a time for AI review. Save ambiguous points as questions and review other requirements while waiting for answers. "Check related sources for contradictions" puts a draft in chat for you to review and send. Paging through the list does not complete a review or confirm the scope.

## The chat on the right, and picking up where you left off

![PM on Rails right-hand chat. Keep the current screen open and point at 'this screen' or 'this story'. Before: you re-pasted context every time. After: you ask about what you are looking at.](https://pmonrails.com/docs-img/chat-side-panel.png)

- **Open it from any screen** — press "Ask AI" in the header and a chat opens on the right of the screen. The same conversation continues as you move between pages, and "Close" keeps it closed. "Open full screen" takes you to the AI assistant screen (on narrow screens it goes straight to full screen).
- **Point at "this screen" or "this story"** — the chat on the right attaches the kind of screen you are on and, on a detail screen, the item it shows (a story, a task and so on) as a hint. List screens attach only the screen kind; nothing extra is fetched.
- **Drafts are not lost** — what you typed on the right stays when you move to another page. If you try to leave while an answer is streaming, it asks whether to interrupt. Pressing a follow-up or "Continue" does not overwrite a draft in progress.
- **Reopening a conversation restores it** — reopening the history brings back not only the text but also the evidence, follow-ups and confirmation cards. Cards you already ran show as "done" and the same creation never runs twice. Answers that were cut short by stop, navigation or a dropped connection are marked "interrupted", so you can press "Continue".
- **How evidence and confirmation cards are shown** — Evidence (sources) is split into **cards by type** (requirement cards, stories, scenarios and so on). Scenario bodies appear in full as Gherkin; everything else as Markdown, **without collapsing**. Confirmation cards stack fields under type headings, and bracketed sections appear as headings.
- **Esc closes it.**

## 1. Look it up and answer (read-only, runs immediately)

| Say this | What the AI does |
| --- | --- |
| "List the requirement cards around login" | Searches across the related requirement cards, requirements, stories, scenarios and tasks, and shows them |
| "Is there a past requirement card similar to this one?" | Searches for requirement cards and requirements that are close in meaning, and shows duplicates and related items |
| "Is there a past decision similar to this requirement card?" | Answers by looking at past decisions and architecture decision records (ADRs) |
| "Which requirement card is this requirement based on?" | Walks traceability back and shows the underlying requirement card and conversation, with citations |
| "What does changing this requirement card affect?" | Follows the downstream stories, scenarios and tasks and shows the impact |
| "How is this project doing?" | Summarises requirement card and task counts, the completion rate, the MoSCoW breakdown and the risk areas |
| "How many tasks are still open?" | Counts tasks by status and answers |
| "Which of my tasks are still open?" | Lists the stories and tasks assigned to you, filtered to the unfinished ones |
| "Put together this week's PM review" | Checks due dates, stalled work, blocked dependencies, unassigned tasks, awaited answers and broken connections in one go |
| "Which questions are still unanswered?" | Looks at the state of the open questions and the feedback from stakeholders |
| "Is there a pull request implementing this task?" | Searches the pull requests in the connected GitHub repository and matches them against the task status |
| "Is the test result for this scenario still valid?" | Looks at test results, how fresh the verification is, and bug and rework trends |
| "What does the database design document say?" | Reads the body and version history of knowledge pages, design documents and meeting notes |
| "Take a look at this Figma / Slack thread / page" (paste a URL) | Fetches the pasted URL and answers (Figma, Slack and private GitHub need the integration to be set up) |
| "How long might this task take?" | Suggests an estimate based on the task details and related specifications |
| "Why is this requirement card a must?" | Explains the reason, with the name of the source and a verbatim quote |

## 2. Create and change (runs once you confirm)

When you ask, the AI shows a **confirmation card describing the change**. Nothing is rewritten until you press Run.

| Say this | What happens after you confirm |
| --- | --- |
| "Raise a requirement card for inventory management" | Creates a new requirement card |
| "Raise the login requirement card to must" | Changes the requirement card's MoSCoW to Must |
| "Create a user story for inventory management" | Creates a new user story |
| "Change this story's actor to the warehouse staff" | Updates the story's overview, actor and business value |
| "Write a Given/When/Then scenario for a successful login" | Creates a new acceptance scenario (a parent story is required) |
| "Add a task for stock lookup" | Creates a new task (task / scenario / bug) |
| "Raise a bug for the crash when stock runs out (severity: critical)" | Creates a bug task (a bug needs a severity) |
| "Mark this task done" | Changes the task's board status |
| "Assign this task to me and set the estimate to 3 hours" | Changes the task's assignee, estimate, due date, priority and labels |
| "Move this task under the inventory management story" | Re-parents the task to another story (or detaches it into a standalone task) |
| "Add a non-functional requirement that responses come back within 3 seconds" | Creates or changes a non-functional requirement or a constraint (functional behaviour goes into stories and scenarios) |
| "Leave a note on this requirement card saying we will revisit it next term" | Leaves a comment on a requirement card, requirement, story, scenario or task |
| "Save this memo to Knowledge" | Creates a document after you review its body, type and destination |
| "Save a design document for this story" | Creates a design document linked to its design targets, checking for existing documents |
| "Record this design decision as an ADR" | Creates an ADR after you review its context, decision, rationale and consequences |
| "Record this test run" | Records the target task, result, observations and evidence from an actual execution |
| "Read the meeting notes and turn them into requirement cards" | Reads the material in knowledge and proposes creating requirement cards from what it found |
| "Create this story and the three scenarios under it in one go" | Proposes several creations together (the confirmation cards line up; up to 20 in one answer) |
| "Group the inventory work into an epic" | Creates or changes an epic (linking what sits under it is done on the roadmap screen) |
| "Create a cycle running from 1 to 14 September" | Creates or changes a development cycle (it asks back if the dates are unclear) |
| "Register our contact at the supplier as a stakeholder" | Creates or changes a stakeholder (a real person's contact details) |
| "Put this requirement card away, we do not need to look at it any more" | Archives or restores a requirement card, requirement, story or scenario |
| "We are dropping this requirement card this term, there is no budget" | Records "postpone to next time" or "out of scope this time" with the reason (adopting is decided on the scope screen) |
| "Delete this duplicated scenario" | Deletes a requirement card, story or scenario (you confirm what gets deleted along with it; this cannot be undone) |

> **The AI never rewrites anything on its own.** Even if you ask it to "mark this done", it acts only after showing you a confirmation card. After it runs, what changed and the next step are left in the conversation.

## 3. It adds observations and hints for improvement

Answers automatically come with the problems in your data, the improvement actions to take, and good questions to ask next.

| Say this | What the AI does |
| --- | --- |
| "Are there any stories with a scenario missing?" | Points out quality risks such as orphans, missing scenarios, stale information and broken connections |
| "How can I make this requirement card better?" | Suggests improvement actions, such as adding requirements or scenarios and making the description more concrete |
| "Which requirements could I link to this story?" | Shows requirements that look related and suggests linking them |

## 4. Draft a document

Ask for a document draft in the conversation, for example, "draft a design memo from this". **The draft is not saved as a document.** Review it, then ask to save this body. A confirmation card shows what will be saved, and approval creates the document. You can also edit and save from the Knowledge or Design docs screen.

On a document creation screen, or while a saved document is open, pressing "Write with AI" or "Rewrite with AI" opens the side chat and **the result lands directly in the editor you have open**. A rewrite based on the open body works the same way, including a body you have not saved yet, so you can review and edit before saving. Note the limits: when you ask about the open body, the AI reads up to the first 8,000 characters of it, and a rewrite can use the whole body as its base only up to 20,000 characters (longer bodies are generated fresh, not based on the old text).

## Scope and limits

- **What you can create or change from a conversation**: requirement cards, requirements (non-functional and constraints), stories, acceptance scenarios, tasks (including bugs), comments, epics, development cycles and stakeholders. Beyond creating and updating, you can archive and restore, delete, re-parent a task to another story, and record a postpone / out-of-scope decision on a requirement card. You can also approve creation of knowledge documents, design documents and ADRs, and record test results from actual executions.
- **What cannot be done from chat**: adopting a requirement card into the current scope, archiving or deleting tasks, deleting requirements, changing a scenario's status (approve, reject, deprecate and so on), deleting epics, cycles or stakeholders, starting and finishing a cycle, linking work under an epic, inviting viewers, updating, deleting or moving existing knowledge and design documents, and changing existing test results and ADRs. Do those from the individual screens or from [Claude Web, Claude Code, and MCP integration](https://pmonrails.com/en/docs/mcp.md) (it can still read them and answer questions about them).
- You can also ask it to edit a scenario that is already settled (active or approved). In that case the agreed version is left untouched and a **new version (a draft)** is created.
- Attachments, images and spreadsheets cannot be read. Paste the content into the message, or register it as a knowledge page.
- Answers are always limited to data inside the project, and never use material you do not have permission to view.

## Next steps

- Do the same things from external tools → [Claude Web, Claude Code, and MCP integration](https://pmonrails.com/en/docs/mcp.md)

---

https://pmonrails.com/en/docs/ai-assistant