# How the AI works

The AI in PM on Rails treats what you have collected **not as a pile of separate documents, but as something held together by meaning**. That is why it can answer from "the facts of your project" more precisely than keyword search or a general-purpose chatbot.

![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)

## How it differs from ordinary search and general-purpose chat

- **It follows the connections to answer** — Example: ask "why is the login requirement card a must?" and it goes back to the remark in the meeting it came from, and even to similar decisions made in the past. Keyword search would only line up documents containing the word "login".
- **It finds things by meaning** — Example: write "I want to strengthen authentication" and it still picks up related requirement cards worded differently, such as "improve login" or "password safety". [Open questions](https://pmonrails.com/en/docs/clarifications.md) are included in search too, so you can follow unanswered questions from the conversation.
- **It answers with evidence** — Example: an answer carries its source, as in "(from requirement card XX) someone said ...". Citations are taken from your real data, so it does not invent sources.
- **It settles in over time** — Example: the kind of candidate you always adopt starts appearing higher up next time.
- **It is safe** — Example: searching in project A never surfaces requirement cards from project B, or meeting notes you do not have permission to view.

## Why holding information as connections (a graph) makes answers precise

PM on Rails holds information as **points and lines (a graph)** rather than as a table of rows and columns. Concretely, it pays off in situations like these.

- **You see the impact straight away** — Example: change the requirement card "how stock counts are handled" and you get a list showing that the 3 stories, 8 tasks and 2 acceptance scenarios hanging off it are affected. With a spreadsheet tool that is a one-by-one cross-check.
- **You can follow relations several hops out** — Example: starting from the task in front of you, "which requirement card did this come from?" runs through task, scenario, story, requirement and requirement card in one go.
- **You can trace the "why" backwards** — Example: from a finished task you can work back to the reason the spec was written that way (the original remark, or the decision to adopt it) and show the evidence.
- **Relations are easy to add later** — Example: to say "this bug affects this scenario", you simply draw the line afterwards. There is no rebuilding of data.

With table-based tools, each of these becomes a manual cross-check every time. Holding information as connections means both the AI and people reach the answer just by following relations.

## Information goes stale — living with freshness

What you have collected drifts away from reality as time passes. The owner changed, the direction changed, the spec was rebuilt — old records survive all of that, so left alone, "the way it used to be" can creep into AI answers and search results. This happens naturally with any tool, and we recommend living with it as follows.

- **The more you keep importing, the fresher it gets** — Import meeting notes and documents continuously and the connections to new information grow, which makes it easier for the AI to favour the latest decisions. The trick is not to treat it as a one-off load at the start.
- **Use the source to check how old the information is** — AI answers carry their source. If an answer feels out of date, follow the source and check the date on the original meeting notes or requirement card.
- **Archive what is finished** — Archiving requirement cards and stories you no longer use takes them out of lists and roll-ups and tidies things up (they remain as history).
- **When you spot a wrong answer, fix the source** — If the source an answer cites no longer matches reality, updating that requirement card or document itself is the real fix. It shows up in later answers.

## Maintaining the knowledge graph

To keep the AI accurate, it matters that the graph is not something you build once and forget. If PMs fold the following into their regular check-ins, developers who trace the graph over MCP later have far less to puzzle over.

- **Add new primary sources** — Import meeting notes, spec change memos, answers to open questions and design decisions as they happen. Do not only fix old requirement cards; add new evidence to the graph.
- **Check the source and its date** — When an AI answer looks suspect, look at the date of the document, requirement card or decision it cites rather than at the answer itself. If it is leaning on old evidence, add or update the latest requirement card or decision.
- **Fix upstream first** — Fixing only the story or the task makes it impossible to trace "why it ended up this way" later. If the original remark or the requirement card changed, update the original document, requirement card and requirement, then push it down into the stories, scenarios and tasks.
- **Close open questions** — Keep the questions raised in AI reviews or conversations in [Open questions](https://pmonrails.com/en/docs/clarifications.md), and mark them resolved once they are answered. Reflect the answer into the requirement cards, requirements and stories too, so the question does not end up floating on its own.
- **Archive rather than delete** — Archive requirement cards and stories you no longer use so they stay as history. We recommend hard deletion only where there is little value in keeping the history, such as duplicates or mistaken entries.
- **Review the diff after a change** — After a re-import or an upstream change, use [Change tracking](https://pmonrails.com/en/docs/change-tracking.md) and the "unreviewed upstream changes" panel on the story screen to confirm nothing was left unreflected downstream.
- **Reduce orphans** — Anything floating on its own — a lone requirement card, a lone story, a lone task — makes it harder for the AI to trace evidence. Use the AI assistant or MCP to check for "stories with no evidence", "stories with no scenario" and "tasks not linked to a requirement card", and add the lines you need.

## Where you can use it

- Use it in conversation → [AI assistant](https://pmonrails.com/en/docs/ai-assistant.md)
- Use it from external tools (Claude Web / Claude Code / Codex) → [Claude Web, Claude Code, and MCP integration](https://pmonrails.com/en/docs/mcp.md)

---

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