Prioritize user-focused documentation

[deboer-tim]

There are three basic types of people that interact with every agent:

• the developers who build the agent
• the 'admins' who install and configure them
• the users who interact with them (typically via GitHub)

Right now, the documentation for each agent covers 2 and 3 and sometimes 1 all at the same time. This makes it confusing to read and can take much longer to understand and find what you need. e.g. the triage agent docs talk about outputting structured JSON and a post-script, configuring a labelling skill, instructions for the agent, the agent output, and variables.

Users will vastly outnumber admins or developers, and all they want to know is what triggers the agent and how it'll behave on GitHub. They don't need to understand how the agent works. Admins will outnumber developers, and just need to know configuration options or how to change behaviour.

Suggestion:

• Remove all internal details from the docs, they don't belong there.
• Clearly separate all sections like 'Configuration' or 'How the agent works' and move to the bottom of the docs (or in a separate pages).
• Remove all references to scripts, OpenShell, JSON, or other internal details from the user section. These can remain in the admin part of the documentation, but only as much as you need to know for configuring the agent.

[rh-hemartin]

/fs-triage

[fullsend-ai-triage]

🤖 Finished Triage · ✅ Success · Started 7:49 AM UTC · Completed 7:53 AM UTC
Commit: 7ada4e0 · View workflow run →

[fullsend-ai-triage]

Triage Summary

Severity: Medium · Category: Documentation

Problem

Agent documentation in docs/ mixes content for three distinct audiences — end users, admins, and developers — without clear separation. Users (the largest group) must read through implementation details like JSON output schemas, post-scripts, and sandbox architecture just to understand what an agent does and how to interact with it.

Recommended Approach

Restructure each of the 7 agent doc files (docs/*.md) with a consistent audience-first hierarchy:

1. User section (top): Triggers, commands, behavior, control labels. No references to scripts, JSON, sandboxes, schemas, or internal mechanics.
2. Admin/Configuration section: Skill overrides, behavior tuning, configuration options.
3. Developer/Internals section (bottom or separate page): Architecture, output schemas, post-script details.

Scope

All 7 agent docs: code.md, fix.md, prioritize.md, retro.md, review.md, scribe.md, triage.md.

Proposed Validation

For each agent doc:
- Verify the first section (before any "Configuration" or "Internals" heading)
  contains no implementation-specific terms (JSON, post-script, sandbox,
  schema, harness, structured output)
- Verify a clear heading boundary separates user content from admin/developer content
- Verify the user section covers triggers/commands and observable behavior

[fullsend-ai-coder]

🤖 Finished Code · ✅ Success · Started 7:54 AM UTC · Completed 8:06 AM UTC
Commit: 7ada4e0 · View workflow run →