Stale docs finder
By Toolspoke
Finds the Confluence pages nobody has updated in months that people still rely on, and posts them to Slack by owner.
Needs a Toolspoke account. You choose which project it installs into.
- Confluence + Slack
- Required integrations
- Runs on a schedule
- First Monday of each month at 10am by default
- Post one message
- What its last step does
- Some actions can delete
- 1 of 30 actions in its tools
On this page
The short version
- What it is
- A ready-made Toolspoke agent that finds Confluence pages that have gone stale where people still look.
- What it reads
- Pages in the spaces you choose that have not changed in 180 days, the space homepage, and each page's place in the tree.
- Where it posts
- One Slack channel, grouped by space and then by owner.
- What it flags
- Old pages near the top of a space, linked from its homepage, with child pages, or titled like a runbook or guide.
- How often
- The first Monday of each month at 10am once you switch it on.
- What it never does
- Edit, move, comment on or create a page, or say a page is wrong.
- What you need
- A Toolspoke account, an Atlassian API token for Confluence, and a Slack workspace.
What Stale docs finder will never do
Stale docs finder is told never to edit, move, retitle or comment on a page, never to create one, and never to say a page is wrong. It cannot delete or archive a page at all. It finds, and the owner decides.
Stale docs finder will never
- Edit, move or retitle a page.
- Comment on a page or create one.
- Say a page is wrong.
- Read or report on spaces that were not chosen at install.
Why it never edits a page
Confluence's update replaces a page's whole body. An agent rewriting an old runbook could remove the one step that still matters. The owner knows what is true now; the agent only knows the date.
Why old is not the same as wrong
A policy that has not changed in a year may be exactly right. The list says how long it has been and why the page matters, and leaves the judgement to the person who owns it.
Why it does not comment
A comment on each page notifies its watchers, one by one. One Slack post reaches the people who can act on all of them at once.
These are written into Stale docs finder's instructions. They guide the agent, but they are not a permission. What it is allowed to touch is set by the access you grant.
Stale docs finder reads Confluence and reports what has gone quiet. Every update and archive is made by a person.
What Stale docs finder does
Stale docs finder is an AI agent that reads your chosen Confluence spaces once a month, finds the pages nobody has updated in months that still sit where people look, and posts them to Slack with who owns each one.
A wiki goes wrong one page at a time. The onboarding guide still names a tool the team dropped, the runbook points at a server that was retired, and the new hire follows both.
Every wiki has hundreds of old pages, and most of them are fine to leave: meeting notes, finished projects, last year's plans. The ones that matter are the old pages people still start from.
Stale docs finder separates the two. It finds pages untouched for six months, then keeps the ones near the top of a space, linked from its homepage, holding other pages under them, or titled like a runbook, a guide or a policy. The rest it counts.
In practice, on the first Monday of each month you get:
- Old pages people are likely to rely on, by space and owner
- The reason each page was listed
- A count of the other old pages, so nothing is hidden
- The decision to update or archive left with the owner
How it works
Stale docs finder works in four steps each month: it finds the old pages, judges which ones people rely on, looks up who owns them and posts one message. All of it comes from the agent's written instructions, which you can read and edit after you install it.
Step 1: Find old pages
It searches each chosen space for pages unchanged in 180 days.
Step 2: Judge which matter
It checks each page's place in the tree and the space homepage.
Step 3: Find the owner
It reads each listed page for its owner and last editor.
Step 4: Post one list
It posts one Slack message, by space and then by owner.
It searches by last change
For each space it calls search_pages with a CQL query such as type = page AND space = ENG AND lastModified < now('-180d'), and pages through every result.
It cannot see page views
The Confluence connection shows no view counts and no list of the pages that link to a page. So the agent uses what it can see: whether the page sits under the space homepage (get_space, list_child_pages), whether the homepage links to it (get_page), whether it has child pages, and whether its title looks like a runbook, onboarding guide or policy. The post says this, so nobody reads the list as analytics.
It names owners when Confluence does
It reads each listed page with get_page for its owner and last editor. Confluence identifies people by account id, so when a name does not come back the post says the owner could not be named and links the page instead of guessing.
It finds and stops
It never edits, moves or comments on a page. The owner decides. The limits are under what it will never do.
What a monthly list looks like
A message from Stale docs finder is one Slack post, grouped by space and then by owner, with the reason each page was listed.
Orbitly
Channels
- # docs
- # engineering
- # people
- # general
# docs
November. ENG and PEOPLE spaces, 318 pages read, 63 unchanged in 180 days, 11 listed. Views are not visible to this agent.
ENG: Marta Kowalski (2)
- New engineer onboarding. 14 months since a change, last edited by Marta. Child of the homepage, onboarding title.
- Deploy runbook. 9 months, last edited by Jon Reyes. Linked from the homepage, runbook title.
PEOPLE: owner not named (1)
- Expense policy. 11 months. Parent of 4 pages, policy title. Confluence returned no name for the owner.
Counted, not listed
52 more pages unchanged in 180 days, with none of the signs above: mostly meeting notes and project pages.
- Near the top
Old pages under the space homepage or linked from it. These are where people start reading, so they matter most.
- Structure and guides
Old pages with child pages under them, or titled like a runbook, guide, policy or process.
- Counted
Old pages with none of those signs. They are counted so the total is honest, and left out of the list.
Why it sometimes says nothing
If no page makes the list, it posts nothing that month.
A failed run is different. If Confluence cannot be read, it posts that once, and a space it could not read is named as not checked, so a short list is never mistaken for a tidy wiki.
Who uses Stale docs finder
Stale docs finder suits teams whose Confluence has grown faster than anyone can keep up with. The examples use made-up names.
An engineering manager before a hiring wave
Marta Kowalski has four engineers starting next month. The list shows her which onboarding and setup pages have not been touched in a year.
An SRE lead who owns the runbooks
Jon Reyes wants every runbook checked twice a year. The runbook titles come up when they pass six months.
A people team with policies to keep current
Aiko Mori's policy pages are read by everyone and changed by almost nobody. The list is her reminder to review them.
A knowledge manager tidying a big wiki
Paul Mensah reads the counted line too. When it grows, he plans an archive day with each space's owner.
What Stale docs finder connects to
Stale docs finder connects to two tools: it reads Confluence and posts to Slack. You connect each one yourself, and Toolspoke stores the credential encrypted, so the agent never sees it.
Confluence
RequiredSearch the wiki, read pages, publish and revise documentation.
Authentication: Atlassian API token
Slack
RequiredSearch conversations and send messages to your workspace.
Authentication: Bot token
| Tool | What Stale docs finder does | What it cannot do |
|---|---|---|
| Confluence | Reads spaces, searches pages by last change, walks the page tree and reads single pages (list_spaces, get_space, search_pages, list_child_pages, get_page). | Delete or archive a page: the connector has no such action. It can create pages, rewrite them and comment, and the agent is told to do none of them. |
| Slack | Posts one list with send_message to the channel you chose. | Delete messages: the connector has no delete action. |
Confluence connects with your Atlassian email and an API token, which reads exactly the spaces you can read. Stale docs finder is told never to edit or comment. That is an instruction, not a lock.
To make it a lock, give this agent read access to Confluence. Creating, rewriting and commenting are all classed as writes, so none of them is reachable on a read grant. The access control guide explains how.
The list is posted to Slack, where page titles from private spaces become visible to the channel. Choose spaces and a channel whose readers overlap.
When Stale docs finder runs
Stale docs finder runs on the first Monday of each month at 10am, but only after you switch its schedule on. It arrives switched off, so nothing runs and nothing is charged until you decide.
- Each run searches every chosen space for pages unchanged in 180 days.
- Pages people are likely to rely on are listed; the rest are counted.
- If no page makes the list, it posts nothing.
- If a space cannot be read, it is named as not checked.
Each run uses model credit from your workspace balance, so it makes one run a month. A large space takes longer, because each listed page is read on its own. The Confluence and Slack calls themselves are free.
Your copy is an ordinary agent in your project. You can pause its schedule, run it on demand, change the age limit and edit its instructions. The agent's page lists recent runs and their cost.
How to set up Stale docs finder
To get a monthly list of stale Confluence pages, add Stale docs finder to a Toolspoke project, connect Confluence and Slack, choose the spaces and channel, and switch on the schedule. Nothing runs until the last step.
Step 1: Create a Toolspoke account or sign in
Choose Use this agent. If you are new, you will be asked to sign up first, and you come straight back to this agent afterwards.
Step 2: Add it to a project
Pick the project it should live in. You get your own editable copy, and you can see the two tools it brings before anything connects.
Step 3: Connect Confluence with read access
Enter your Atlassian site name, then your account email and an API token from your Atlassian account settings. Give the agent read access, so it cannot edit or comment.
Step 4: Connect Slack
Choose Sign in with Slack and approve the Toolspoke app. For a private channel, add the Toolspoke bot to it first.
Step 5: Choose the spaces and age
Name the space keys to read, such as ENG or PEOPLE, the channel, and how many days without a change make a page stale.
Step 6: Switch on the schedule
The schedule arrives switched off. Run it once and read the list, then switch it on.
Make Stale docs finder fit your wiki
Stale docs finder's instructions are plain English and you can edit them after you install it. Installing copies the agent, so your edits stay with your copy. Open the agent in Toolspoke and tell the builder what to change.
Paste any sentence below into the builder chat, or say the same thing in your own words.
Treat pages with runbook in the title as stale after 90 days, and everything else after 180.
Ignore pages whose title starts with Meeting notes or Retro.
Also list old pages titled like an architecture decision or an incident review.
List every page unchanged in 180 days, not only the ones near the top of a space.
Run on the first Monday of January, April, July and October.
This changes when the agent wakes up, so the builder edits its schedule, not the instructions.
None of these edits needs more access or touches the Never rules. They change what Stale docs finder is told, not what the connections allow.
How it compares to other options
Stale docs finder beats the alternatives when you want the old pages that matter, sent to you monthly, without an analytics add-on, and loses to them when you need real view counts.
| Compared on | Stale docs finder | A CQL search you run yourself | Confluence analytics | A documentation review rota |
|---|---|---|---|---|
| Finds pages by last change | Yes | Yes | Yes | If someone looks |
| Knows how often a page is read | No, uses signs instead | No | Yes, on plans that include it | From experience |
| Separates important pages from old notes | Yes, from tree, links and title | No | By views | Yes |
| Comes to you each month | Yes, in Slack | You run it | You open it | If the rota holds |
| Setup effort | Connect two accounts | Write the query | A plan that includes it | Ongoing people time |
Confluence analytics is the better choice when your plan includes it and you want to know which pages people actually open. Stale docs finder cannot see views, and says so.
A review rota is better when the docs are a product in themselves, such as a public help centre, and need a person reading every page on a schedule.
Frequently asked questions
Does Stale docs finder know which pages people read?
No. The Confluence connector shows no page views and no incoming links. It uses where a page sits, whether the homepage links to it, whether it has child pages and its title instead, and says so in each post.
Can it archive or delete old pages?
No. The Confluence connector has no archive or delete action. It can rewrite pages and comment, and the agent is told never to; give it read access to make that a lock (how access works).
Why does a row say the owner could not be named?
Confluence identifies people by account id, and sometimes no display name comes back. The agent links the page rather than guessing who owns it.
Which spaces does it read?
Only the ones you name at install, and only if the account behind the API token can read them.
Is Stale docs finder free?
It has no price of its own, and every Toolspoke plan includes agents. Tool calls cost nothing, but each run draws on your usage balance. Pricing has the details.
Find the pages that need a second look
Connect Confluence with read access and Slack, choose your spaces and switch on the schedule. Your first list arrives on the first Monday of next month.