Pay down docs debt with Deep Analysis
Overview
Section titled “Overview”Use Deep Analysis when a documentation project spans many pages, needs background research, or calls for a plan before any edits land. Promptless plans the work, splits it into parts, and runs its full writing workflow on each part. You get a coordinated set of suggestions in place of a single edit.
Deep Analysis fits projects like these:
- Refactor or rewrite a whole section to match a new pattern or stronger examples.
- Audit the collection for consistency, accuracy, or style compliance.
- Write documentation from scratch for a new feature or product.
- Add error codes, examples, or other structured data across an OpenAPI reference.
Deep Analysis is one of three modes on the New Task page. Choose the mode that fits the size of the request:
| Mode | Best for | Expected response | Typical output |
|---|---|---|---|
| Fast | Typos and small wording fixes | Under 5 minutes | Usually 1 suggestion |
| Default | Most documentation changes | 10–20 minutes | Usually 1–2 suggestions |
| Deep analysis | Audits, migrations, and multi-page work | Can take hours | Often 10 or more suggestions |
For routine updates, use a regular trigger, such as Slack or a GitHub PR trigger, or a New Task in Default mode.
Submit a request
Section titled “Submit a request”-
In the sidebar, select New task. To open the New Task page with Deep analysis already selected, use the Deep Analysis link.
-
Optional. To scope the run yourself, choose a collection from the Doc Collection chip. The default, Let Promptless decide, picks the collections the task affects. Only collections that have finished initial analysis appear in the list.
-
In the Mode chip, select Deep analysis.
-
Optional. Under Use a template, select a Deep Analysis template. Do this before you write: a template replaces anything already in the instructions field.
-
In the instructions field, describe the project. Include the product area, the source code or APIs Promptless should inspect, examples to model, and the changes to focus on.
-
Optional. To add screenshots, PDFs, or specs, select Attach files (the paperclip) or paste an image into the field. You can attach up to 5 files, 10 MB each.
-
Optional. Change where Promptless reports on the task in Slack. The Notify control opens on the Slack channel your
promptless.yamlpolicies route notifications to, or your escalation channel when that’s the only one set. Promptless sends this task’s suggestions and blockers to that channel, and keeps its other messages in the task conversation. Choose another channel, or select No notification to keep the task out of Slack entirely, blockers included. Microsoft Teams channels in your policies get notified whatever you choose here. -
Optional. Turn on Auto-create PRs to open a pull request for each of this task’s suggestions without reviewing it first.
-
Select the submit arrow, or press Cmd+Enter on macOS or Ctrl+Enter on Windows and Linux. Pressing Enter alone adds a new line.
Promptless opens the task’s conversation page. The run continues in the background, so you can close the tab. To follow the run and reply to it, see Follow and reply in the task conversation.
Choose a template
Section titled “Choose a template”The Use a template rail includes four Deep Analysis templates for common project shapes. Each one fills the instructions field with a title line, a description, and {curly-brace} placeholders for the context Promptless needs. Edit the text before you submit. Selecting a template also sets Mode to the mode it needs, and selecting the selected card again clears the field.
| Template | Use it to |
|---|---|
| Refactor a bad section of docs | Improve an existing section, using another set of docs as a model. |
| Add error codes to OpenAPI spec | Add error codes and examples to your API specification. |
| Write docs from scratch | Write new documentation, with guidance on outline, audience, and style. |
| Audit for consistency | Review all documentation for consistent terminology, formatting, and structure. |
The rail’s other templates, such as Find doc update from recent merges, run in Default mode.
Follow a Deep Analysis run
Section titled “Follow a Deep Analysis run”A Deep Analysis run can take several hours and often produces 10 or more suggestions across your documentation. Promptless plans the work across your docs first, then runs the full writing workflow for each part: research, grounding in your source, editing, and review.
The run appears on the Triggers page as Deep Analysis: <your instructions>, so you can tell it apart from regular tasks. Promptless posts progress in the task’s conversation as the run works. If you chose a notification channel, Promptless also posts there when the suggestions are ready for review and when it needs your input to continue.
Follow and reply in the task conversation
Section titled “Follow and reply in the task conversation”Every New Task, in any mode, opens a conversation page in the dashboard. Promptless acknowledges your request there, posts progress, and answers you or asks a clarifying question. It also reports the outcome, even when no documentation change is needed. The suggestions the task produces appear in the conversation as they’re ready. Any member of your organization can read the conversation and reply, and each message shows its author.
Reply to a task
Section titled “Reply to a task”Reply on the conversation page to add instructions, answer a question, or ask for more work:
- While the task runs, Promptless takes your reply into the running task.
- After the task finishes, your reply starts a follow-up task in the same conversation. The follow-up carries the conversation so far and keeps the original task’s doc collection, mode, Auto-create PRs setting, and Notify choice.
To start a follow-up, enter your request in the reply field of the finished task and select the send arrow (Start follow-up).
Attach files to a reply
Section titled “Attach files to a reply”To send a screenshot, spec, or other file with a reply, select Attach files (the paperclip) in the reply field. You can also paste an image into the field. A reply needs a message and can carry up to 5 files, 10 MB each. Each message in the conversation lists its files by name and size.
- A reply to a running task delivers its files to that task with your message.
- A follow-up task receives every file attached earlier in the conversation, plus the files on the reply that starts it.
Each follow-up carries all of those files, so a conversation holds at most 25 files and 100 MB in total. The limits count the New Task’s files and every reply’s. When a reply’s files would pass either limit, Promptless doesn’t send the reply and keeps your draft in the reply field. Remove the files and send the reply again, or start a new task to share more files.
Return to a task
Section titled “Return to a task”The Recent tasks list in the dashboard sidebar shows your organization’s task conversations active in the last 90 days. The task’s row on the Triggers page and Promptless’s Slack notifications for the task also link to its conversation.
Tasks submitted over MCP or the API appear in Recent tasks too, and you can reply to one while it runs. After such a task finishes, its conversation is read-only in the dashboard, because the client that submitted it decides what happens next. To continue the work from the dashboard, start a new task.
See also
Section titled “See also”- Audit and keep your docs healthy, for how Deep Analysis fits into a docs remediation project
- Teach Promptless a custom task, for recurring work that a trigger starts
- Get support, for help scoping a Deep Analysis project