operately Help Docs — Change Discovery
Scan git history since a baseline, identify user-facing product changes, and infer how they work from source code.
This skill covers finding what needs documenting and how the feature works in the UI.
For git commands, path watchlists, filter heuristics, code research guidance, and what to capture per candidate, read reference.md.
Input
Required: baseline SHA or tag (e.g. v1.6.0, abc1234).
If the user does not provide a baseline, ask before proceeding.
Scope
- Work in the operately repo (this repo).
- Quote UI labels exactly from source; do not polish copy.
- Optionally cross-check the sibling
operately-websiterepo for existing help pages when it is available on disk.
Workflow
1. Resolve baseline
Validate the SHA or tag exists. Record the range baseline..HEAD, HEAD SHA,
and commit count.
2. Collect changes
List merge commits and PR titles in the range. Prefer PR titles over individual
commit messages — PR titles use the feat: / fix: / chore: / docs:
prefixes.
Use the git recipes in reference.md to gather commits and diffs.
3. Filter to user-facing
Keep changes that affect what users see or do in the app. Drop internal-only work (refactors, CI, tests-only, backend-only, migrations without UI impact). See reference.md — Filter heuristics.
4. Cluster related commits
Group commits by feature area. Multiple PRs for one capability (e.g. billing page + checkout + cancellation) become a single item.
5. Research each cluster in code
For each cluster, read the relevant source to infer behavior:
app/assets/js/pages/— screens and navigationapp/assets/js/features/— feature UI and flowsturboui/src/— shared componentsapp/assets/js/routes/paths.tsx— new or removed routesapp/test/features/— user flows (for validation, not as doc content)specs/— product intent for major features
Extract entry points, UI labels, step order, permissions, and edge cases. See reference.md — Code research map.
6. Classify and document each cluster
For each cluster, assign a doc action and capture the findings listed in reference.md — What to capture.
| Action | When |
|---|---|
new_page |
New user capability with no matching help page |
update_page |
Existing flow, labels, or navigation changed |
api_auto_sync |
External API surface changed — CI publishes to /help/api/ |
skip |
Internal-only; no user-facing doc impact |
When operately-website is available, check src/config/helpCenter.js and
src/content/docs/help/ to decide between new_page and update_page.
Also record excluded commits and why they were skipped.
Definition of Done
Before finishing, verify:
- Baseline validated; range and commit count stated
- Internal-only changes listed with reasons
- Each candidate cites source commit SHAs and changed file paths
- UI labels quoted exactly from code
- Existing help pages referenced when the website repo is available