docs(factories): deep content pass — accuracy against product, tone, and cross-linking - #558
Merged
guyscherzer8 merged 3 commits intoAug 18, 2026
Conversation
Follow-up to #557's mechanical pass, addressing the deeper audit asked for on #508: tone consistency, missing cross-links, and accuracy against the product. Accuracy (verified against warp-server's factory frontend): - Drop the Time saved metric from control-room and measure-and-improve; the dashboard card was removed (client/packages/factory api/metrics.ts). - Rename PR latency to PR cycle time to match the card label, and align the metric's definition on both pages (kickoff → PR → first review → merge, per-stage medians). - Align the Autonomy definition on both pages with the product semantics: no human input beyond an approving review and the merge itself. - Align control-room's Live-managed description with the product copy (managed through the API). Links: - Convert 9 relative links in factory-as-code to root-absolute; they resolved to /factories/... paths and 404'd in production (same class of bug #557 fixed; this page landed after that sweep). - Add missing cross-links: quickstart → control room + platform credits, factory-agents → control room, control-room/infrastructure → credentialStrategy, control-room → Self-improvement anchor, how-factories-work → PR checks anchor, Slack Home tab → Activity view, Linear prereq → GitHub connection, troubleshooting → integration troubleshooting sections. - Add the missing Linear entry to connect-your-factory's default automations list. Tone and consistency: - Rewrite the Linear intro: present tense, correct stage names (it claimed a spec/implement/review/verify pipeline), direction consistent with sibling pages, and a lifecycle link. - Normalize Scorer / Self-improvement capitalization across pages. - Replace the 'Oz model ID' coinage with a model_id reference linked to the model catalog. - Trim inward-facing phrasing (Early Access note) and a roadmap promise (Jira caution); fix future tense and em dashes in the quickstart. Validated: npm run build passes, style_lint clean on touched files, link checker reports 0 broken links. Co-Authored-By: Warp <agent@warp.dev>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
Collaborator
Author
|
This PR was generated with Warp. Comment   |
Contributor
|
Your Warp account is not a member of any team with access to this repository. |
The Prerequisites section already states a factory needs a team with credits. Co-Authored-By: Warp <agent@warp.dev>
hongyi-chen
marked this pull request as ready for review
August 18, 2026 00:21
Contributor
|
I'm starting a first review of this pull request. You can view the conversation on Warp. I completed the review and no human review was requested for this pull request. Comment Powered by Oz |
… Foreman name label, drop the redundant credits note Co-Authored-By: Warp <agent@warp.dev>
![oz-for-oss[bot]](https://avatars.githubusercontent.com/in/3450139?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Overview
This PR makes targeted documentation edits across the Warp Factories pages to align metric terminology, integration descriptions, capitalization, and cross-links. I reviewed the attached annotated diff, PR description, and spec context; the changes are documentation-only, and no approved/repository spec context was available for implementation drift checks.
Concerns
- No blocking concerns found.
Verdict
Found: 0 critical, 0 important, 0 suggestions
Approve
Comment /oz-review on this pull request to retrigger a review (up to 3 times on the same pull request).
Powered by Oz
hongyi-chen
added a commit
that referenced
this pull request
Aug 18, 2026
…uide references (#560) Second consistency pass over the launch stack, cross-checking the docs against the product and against each other after #557/#558/#559 landed. Verified against warp-server (no change needed): - The alias constraints in factory-as-code match the shared factoryalias.Normalize contract (60 runes; letters, digits, spaces, '-', '_', '.'; case-insensitive uniqueness). - Activity's terminal stage really is labeled 'Complete' while the Slack Home tab uses 'Completed' (slack_app_home.go) — both pages correctly reflect their own surface, so the apparent mismatch stands. Aligned: - factory-as-code: bridge the alias key to its control-room label, Foreman name (#559 introduced the label in the quickstart), and say it @-mentions the foreman, matching the UI copy. - control-room Settings: name the identity fields (name, avatar, Foreman name) and link Foreman name to the alias reference. - run-a-software-factory-in-the-cloud: DIY-loop runs appear in the cloud agent dashboard, not the Factories product's dashboard — use {VARS.DASHBOARD}. - The five DIY-factory guides framed the Factories product page as 'the conceptual overview of the full loop'; their next-step descriptions now say what the destination is (the managed product), and build-a-self-improving-agent deep-links the Self-improvement section it parallels (the reverse link already existed). - set-up-a-software-factory and run-a-software-factory-in-the-cloud intros now point readers to Warp Factories as the managed alternative. Validated: npm run build passes; link checker 3,664 internal / 1,522 external, 0 broken; style_lint adds no new findings on touched files. Co-authored-by: hongyi-chen <hongyigma@gmail.com> Co-authored-by: Warp <agent@warp.dev> Co-authored-by: Hong Yi Chen <hongyi@warp.dev>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Deep content pass over the 16 Factories pages on
hyc/factory-launch(#508), following up on #557 — which covered links and cross-page seams but was, by its own admission, mechanical. This pass covers the three axes asked for in the #508 review comment: tone/messaging consistency, missing cross-link synergies, and engineer-usefulness (accuracy, no internal leakage, no fluff). 13 files, +49/−46 — every change is a targeted fix, not a rewrite.Accuracy fixes (ground-truthed against
warp-server)Rather than judge prose in isolation, I checked the dashboard claims against the factory frontend (
client/packages/factory):control-roomandmeasure-and-improve. The card was removed from the product (api/metrics.ts: "no card renders it since the Time saved card was removed"), and the two pages had also drifted into different definitions of it.PRLatencyBarsCard.tsx). Both pages now share one definition: median from run kickoff through PR, first review, and merge, with a per-stage median.measure-and-improvesaid "merged work that shipped without human edits"; the product counts comments, change requests, and PR actions as touches too. Both pages now match the card semantics: no human input beyond an approving review and the merge itself.control-roomsaid they're "edited directly in the control room"; the product copy says they're managed through the API (FactoryCode/index.tsx). Aligned.Link fixes and missing synergies
factory-as-code.mdx:../platform/secrets-style relative links that resolve to/factories/platform/...and 404 — the exact bug class docs(factories): full content pass over the launch stack — link fixes and cross-page seams #557 swept, but this page landed after that sweep. Converted to root-absolute.factory-agents→ control room;control-roomandinfrastructure-and-security→credentialStrategyreference;control-room→ Self-improvement anchor;how-factories-work→ PR-checks anchor; Slack Home tab → Activity view; Linear prereq → GitHub connection;troubleshooting→ the three integration guides' troubleshooting sections.connect-your-factory's default-automations list omitted Linear, though the Linear guide documents the default agent-session automation. Added.model_idlinked to the model-choice catalog, which also answers the reference reader's "what values canmodeltake?"Tone and consistency
factory-agentsexplicitly documents that no verify role exists. Now present tense, correct stages, sibling-consistent, with a lifecycle link.e.g.,→such as.Left alone:
integrations/github.mdx(stub deferred to #526), the GitLab TODO inautomation-filters(#549), and the overview's heading style, which matches the sibling overview pages.Validation
npm run build— passesstyle_lint— 0 issues in touched files