docs(vision): frame autonomy as configurable per workflow

[ralphbean]

Summary

• Keeps "everything autonomous" as the lede
• Adds per-workflow configurability: each ASDLC phase can be human-driven, agent-driven, or both
• Frames adoption as incremental — teams shift one phase at a time as confidence grows

Incorporates feedback from Romain on the vision doc.

Test plan

• Verify doc renders correctly on the website
• Review wording with Romain

🤖 Generated with Claude Code

[fullsend-ai-review]

🤖 Finished Review · ✅ Success · Started 3:53 PM UTC · Completed 4:04 PM UTC
Commit: 8217b39 · View workflow run →

[qodo-code-review]

PR Summary by Qodo

Vision: describe per-workflow configurable autonomy with incremental adoption

📝 Documentation 🕐 10-20 Minutes

AI Description

• Reframe the vision lede to keep “everything autonomous” as the explicit end state.
• Define autonomy as configurable per workflow/phase (human-driven, agent-driven, or both).
• Position rollout as incremental adoption rather than a single “flip the switch” change.

Diagram

graph TD
  A["docs/vision.md"] --> B["Goal framing"] --> C["Guardrails"] --> D["Per-workflow config"] --> E["Autonomy modes"] --> F["Incremental adoption"]

Loading

High-Level Assessment

The following are alternative approaches to this PR:

1. Add a phase × autonomy matrix (table)

• ➕ Makes “configurable per phase/workflow” concrete and scannable
• ➕ Reduces ambiguity about what exactly is configurable
• ➖ More verbose and may require ongoing maintenance as phases evolve
• ➖ Could prematurely imply an implementation spec rather than a vision

2. Introduce a short, explicit example snippet (YAML/pseudocode)

• ➕ Clarifies what “configured per workflow” means operationally
• ➕ Aligns expectations for future tooling/config surface
• ➖ Risks locking in an interface too early
• ➖ Adds implementation flavor to a vision doc

Recommendation: The PR’s prose-first approach is appropriate for a vision document and keeps the narrative flexible. If reviewers still find “per workflow” abstract, the best follow-up would be a small table (phase × autonomy mode) rather than a config snippet, to stay conceptual while improving clarity.

Files changed (1) +4 / -4

Documentation (1) +4 / -4

vision.mdReframe autonomy as a configurable, incremental path to full autonomy +4/-4

Reframe autonomy as a configurable, incremental path to full autonomy

• Updates the goal section to lead with “everything autonomous” while clarifying that the path is incremental. Renames “guarded paths” to “guardrails” and adds an explicit per-workflow/per-phase configurability model (human-driven, agent-driven, or both), plus a minor wording tweak in the bugfix workflow description.

docs/vision.md

[github-actions]

Site preview

Preview: https://96d9e235-site.fullsend-ai.workers.dev

Commit: 4b78af2310dc466dbddab81764b6a7aaaec9832b

[qodo-code-review]

Code Review by Qodo

🐞 Bugs (1) 📘 Rule violations (0) 📜 Skill insights (0)

Context used

✅ Compliance rules (platform): 54 rules

✅ Skills: writing-user-docs, writing-adrs

1. Human-factors doc now stale 🐞 Bug ⚙ Maintainability

Description

docs/problems/human-factors.md explicitly frames its analysis around the vision’s “two points of
human participation” model, but the updated vision now emphasizes per-workflow/per-phase
configurability and incremental adoption. Leaving human-factors.md unchanged makes the documentation
set internally inconsistent and can mislead readers about what the current vision actually claims.

Code

docs/vision.md[10]

+Getting there is incremental. Each phase and transition in the [agentic SDLC](#the-agentic-sdlc) can be configured — per workflow — as human-driven, agent-driven, or both. A bugfix workflow might run fully autonomously while a feature workflow keeps a human in the loop at refinement and review. Teams adopt at whatever pace builds confidence, shifting one phase at a time rather than flipping a giant switch.

Relevance

⭐⭐⭐ High

They routinely fix downstream doc drift after source changes; multiple accepted “stale docs”
corrections across docs.

PR-#1039
PR-#1053

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The human-factors doc directly cites the vision as defining a fixed two-point model, while the
updated vision introduces per-phase configurability, so the downstream analysis no longer matches
the source-of-truth document it references.

docs/problems/human-factors.md[88-96]
docs/vision.md[5-10]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
`docs/problems/human-factors.md` depends on the vision stating a fixed “two-point model” (strategic intent + guarded paths; everything else autonomous). The updated vision text introduces per-workflow configurability across SDLC phases, which changes that premise.

## Issue Context
You can fix this either by:
- updating `human-factors.md` to explicitly state it is analyzing the earlier/fixed two-point framing (historical model), or
- updating it to analyze the configurable-per-phase model (or contrast both models).

## Fix Focus Areas
- docs/vision.md[5-10]
- docs/problems/human-factors.md[88-96]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

2. Guardrails term mismatch ✓ Resolved 🐞 Bug ⚙ Maintainability

Description

The vision doc renames the human approval concept to "Guardrails" but elsewhere (including later in
the same file) the docs still use "guarded paths" for the CODEOWNERS-gated areas. This inconsistent
terminology makes it harder to follow cross-doc discussions of CODEOWNERS-gated approval and what
exactly is being protected.

Code

docs/vision.md[R7-8]

1. **Strategic intent** — defining what the system should do and become. Features, architecture, direction.
-2. **Guarded paths** — CODEOWNERS-enforced human approval for security-critical, API-changing, or architecturally significant code paths.
+2. **Guardrails** — CODEOWNERS-enforced human approval for security-critical, API-changing, or architecturally significant code paths.

Relevance

⭐⭐⭐ High

Repo enforces terminology consistency via doc-wide renames (e.g., implementation→code) and other
consistency fixes.

PR-#194
PR-#2334

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

Within docs/vision.md, the list item uses “Guardrails” while the later workflow paragraph still says
“approve guarded paths”. Additionally, other docs consistently use “guarded paths,” indicating the
repo-wide canonical term has not been updated.

docs/vision.md[7-10]
docs/vision.md[38-38]
docs/problems/autonomy-spectrum.md[36-40]
docs/ADRs/0002-initial-fullsend-design.md[49-54]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
`docs/vision.md` introduces the label “Guardrails” for CODEOWNERS-gated approval, but the rest of the doc set (and even later in `docs/vision.md`) continues using “guarded paths”. This creates terminology drift for the same concept.

## Issue Context
The repository has multiple docs that use “guarded paths” as the canonical term; either update the vision back to that term, or do a coordinated rename across docs (and update the remaining occurrence in `docs/vision.md`).

## Fix Focus Areas
- docs/vision.md[7-8]
- docs/vision.md[38-38]
- docs/problems/autonomy-spectrum.md[36-40]
- docs/ADRs/0002-initial-fullsend-design.md[49-54]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

3. Unclear autonomy model ✗ Dismissed 🐞 Bug ≡ Correctness

Description

In docs/vision.md the intro states humans participate at "two points", but immediately after it says
each SDLC phase/transition can be configured per-workflow as human-driven, agent-driven, or both.
This makes the intended steady-state vs incremental-migration model ambiguous and can mislead
readers about what "everything autonomous" concretely means.

Code

docs/vision.md[R5-10]

+Everything autonomous is the goal. A GitHub organization's repos operate with agents handling the full software development lifecycle: issue triage, implementation, code review, testing, and merge-to-production. Humans participate at two points:

1. **Strategic intent** — defining what the system should do and become. Features, architecture, direction.
-2. **Guarded paths** — CODEOWNERS-enforced human approval for security-critical, API-changing, or architecturally significant code paths.
+2. **Guardrails** — CODEOWNERS-enforced human approval for security-critical, API-changing, or architecturally significant code paths.

-Everything else is autonomous.
+Getting there is incremental. Each phase and transition in the [agentic SDLC](#the-agentic-sdlc) can be configured — per workflow — as human-driven, agent-driven, or both. A bugfix workflow might run fully autonomously while a feature workflow keeps a human in the loop at refinement and review. Teams adopt at whatever pace builds confidence, shifting one phase at a time rather than flipping a giant switch.

Relevance

⭐⭐⭐ High

Team has revised “two-point model” framing before; PR #24 explicitly questions it, suggesting
they’ll clarify ambiguity.

PR-#24

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The vision doc asserts a fixed "two points" human participation model and then immediately
introduces per-phase configurability, which implies humans may participate in more than two places
depending on workflow configuration.

docs/vision.md[5-10]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
`docs/vision.md` currently mixes two different framings back-to-back: (1) humans participate at exactly two points, and (2) each SDLC phase/transition can be configured per workflow as human-driven/agent-driven/both. This reads as internally inconsistent and makes it unclear whether per-workflow configurability is only an adoption strategy or also part of the long-term model.

## Issue Context
Other docs reference the vision's “two-point model”, so ambiguity here propagates into the rest of the documentation set.

## Fix Focus Areas
- docs/vision.md[5-10]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[fullsend-ai-review]

Review

Note: The new commit (4b78af23) restores the "everything else" phrasing to preserve cross-doc consistency with human-factors.md — this addresses the [stylistic-consistency] finding from earlier runs. The two medium findings below are unchanged from the prior review.

Findings

Medium

• [terminology-consistency] docs/vision.md:8 — The change from "Guarded paths" to "Guardrails" creates cross-document terminology inconsistency. The term "guarded paths" appears in 16 other locations across 6 files (ADR 0002, autonomy-spectrum.md, intent-representation.md, human-factors.md, security-threat-model.md). Critically, human-factors.md:90 directly cross-references vision.md's phrasing: "The vision defines two points of human participation: strategic intent and guarded paths." After this PR, that cross-reference would use mismatched terminology. Additionally, "guardrails" already has a distinct meaning across 44+ occurrences in 21 files — system-level safety mechanisms (org-wide constraints, agent configuration, sandboxing). AGENTS.md:146 uses "guardrails" in this broader sense: "Agents cannot modify their own guardrails." The rename conflates two previously distinct concepts.
  Remediation: Either keep "Guarded paths" in vision.md to preserve existing terminology, or rename "guarded paths" across all affected files in a single coordinated PR and disambiguate from the existing broader "guardrails" usage.

• [unsubstantiated-architecture-claim] docs/vision.md:10 — The added paragraph claims "Each phase and transition in the agentic SDLC can be configured — per workflow — as human-driven, agent-driven, or both." This uses present tense ("can be configured") implying existing capability. AGENTS.md:141 documents the autonomy model as "Binary per-repo, with CODEOWNERS enforcing human approval on specific paths." autonomy-spectrum.md:7 confirms: "The autonomy model is binary per-repo with CODEOWNERS as the escape hatch." No documentation of per-workflow configuration exists; autonomy-spectrum.md frames finer granularity as an open question (line 69: "The binary per-repo model is simple but coarse"). For a vision document that serves as a key cross-reference, present-tense claims about non-existent capabilities can mislead readers.
  Remediation: Use future tense or aspirational framing ("will be configurable" or "the goal is to allow configuration per workflow"), or describe the current binary per-repo model and position per-workflow granularity as a planned evolution.

---

Labels: PR modifies documentation in docs/ directory

Previous run

Review

Findings

Medium

• [terminology-consistency] docs/vision.md:8 — The change from "Guarded paths" to "Guardrails" creates cross-document terminology inconsistency. The term "guarded paths" appears in at least 15 other locations across documentation files (ADRs, problem docs, human-factors.md, security-threat-model.md, autonomy-spectrum.md, intent-representation.md, testing-agents.md) and web/public/index.html. These files reference "guarded paths" as the canonical term defined in vision.md. Additionally, "guardrails" is already used extensively throughout the codebase (~40+ occurrences) with a distinct meaning — system-level safety mechanisms (org-wide guardrails, sandbox guardrails, configuration guardrails). The rename conflates two previously distinct concepts; line 64 of vision.md itself already uses "guardrails" in the broader sense ("automated testing as primary guardrails").
  Remediation: Either update all documentation files to use "Guardrails" consistently (and disambiguate from the existing broader "guardrails" concept), or keep "Guarded paths" in vision.md to preserve terminological clarity.

• [unsubstantiated-architecture-claim] docs/vision.md:10 — The added paragraph claims "Each phase and transition in the agentic SDLC can be configured — per workflow — as human-driven, agent-driven, or both." This is stated in present tense as existing capability. AGENTS.md documents the autonomy model as "Binary per-repo, with CODEOWNERS enforcing human approval on specific paths" — not per-workflow. The autonomy-spectrum problem document describes the model as binary per-repo, and notes whether per-repo binary is "too coarse" as an open question. No ADRs describe per-workflow configuration. The present tense "can be configured" implies existing capability rather than aspirational direction.
  Remediation: Either reword to future tense ("will be configurable") or qualify as aspirational ("The target model allows..."), or if per-workflow configuration exists, add references to supporting ADRs/architecture.

Low

• [missing-authorization] docs/vision.md — Documentation change with no linked issue. The PR restructures the vision document to frame autonomy as configurable per-workflow rather than binary per-repo, changes terminology from "Guarded paths" to "Guardrails", and adds a paragraph about incremental adoption.
  Remediation: Consider creating a tracking issue that describes the scope of the vision.md reframing.

Previous run

Review

Findings

Medium

• [terminology-consistency] docs/vision.md:8 — The change from "Guarded paths" to "Guardrails" creates cross-document terminology inconsistency. The term "guarded paths" appears in at least 15 other locations across documentation files (ADRs, problem docs, human-factors.md, security-threat-model.md, autonomy-spectrum.md, intent-representation.md, testing-agents.md) and web/public/index.html. These files reference "guarded paths" as the canonical term defined in vision.md. Additionally, "guardrails" is already used extensively throughout the codebase (~40+ occurrences) with a distinct meaning — system-level safety mechanisms (org-wide guardrails, sandbox guardrails, configuration guardrails). The rename conflates two previously distinct concepts; line 64 of vision.md itself already uses "guardrails" in the broader sense ("automated testing as primary guardrails").
  Remediation: Either update all documentation files to use "Guardrails" consistently (and disambiguate from the existing broader "guardrails" concept), or keep "Guarded paths" in vision.md to preserve terminological clarity.

• [unsubstantiated-architecture-claim] docs/vision.md:10 — The added paragraph claims "Each phase and transition in the agentic SDLC can be configured — per workflow — as human-driven, agent-driven, or both." This is stated in present tense as existing capability. AGENTS.md documents the autonomy model as "Binary per-repo, with CODEOWNERS enforcing human approval on specific paths" — not per-workflow. The autonomy-spectrum problem document describes the model as binary per-repo, and notes whether per-repo binary is "too coarse" as an open question. No ADRs describe per-workflow configuration. The present tense "can be configured" implies existing capability rather than aspirational direction.
  Remediation: Either reword to future tense ("will be configurable") or qualify as aspirational ("The target model allows..."), or if per-workflow configuration exists, add references to supporting ADRs/architecture.

Low

• [missing-authorization] docs/vision.md — Documentation change with no linked issue. The PR restructures the vision document to frame autonomy as configurable per-workflow rather than binary per-repo, changes terminology from "Guarded paths" to "Guardrails", and adds a paragraph about incremental adoption.
  Remediation: Consider creating a tracking issue that describes the scope of the vision.md reframing.

---

Labels: PR modifies documentation in docs/ directory

Previous run (2)

Review

Findings

Medium

• [terminology-consistency] docs/vision.md:8 — The change from "Guarded paths" to "Guardrails" alters an established term used across 8+ documentation files (ADRs, problem docs, human-factors.md, security-threat-model.md, AGENTS.md). "Guarded paths" specifically refers to CODEOWNERS-enforced code paths requiring human approval, while "Guardrails" is used elsewhere in the codebase to refer to broader system-level safety mechanisms (sandboxing, policies, org-wide constraints). The explanatory text after the bold term is preserved, but the label change creates cross-document inconsistency.
  Remediation: Preserve "Guarded paths" in this context, or if the rename is intentional, plan a follow-up to update references across all documentation files.

• [internal-consistency] docs/vision.md:38 — The bolded concept name on line 8 uses "Guardrails" but the description paragraph on line 38 still says "approve guarded paths", creating an internal inconsistency within the same document where two different terms are used for the same concept.
  Remediation: Use consistent terminology throughout the document — either both locations should use "guarded paths" or both should use "guardrails".

• [unsubstantiated-architecture-claim] docs/vision.md:10 — The added paragraph claims "Each phase and transition in the agentic SDLC can be configured — per workflow — as human-driven, agent-driven, or both." No other documentation (architecture.md, ADRs, problems/) describes per-workflow configuration of SDLC phases. The existing architecture describes per-repo autonomy (AGENTS.md: "Binary per-repo, with CODEOWNERS enforcing human approval on specific paths"). The present-tense "can be configured" implies existing capability rather than aspirational direction.
  Remediation: Qualify the claim as aspirational ("will be configurable" or "the goal is for each phase..."), or add a brief note that this is the design direction rather than current state.

Low

• [stylistic-consistency] docs/vision.md:38 — The phrase "everything else is autonomous" is changed to "the rest is autonomous", weakening rhetorical parallelism with the standalone sentence earlier in the document and breaking a cross-document reference in human-factors.md line 90 which quotes the original phrasing verbatim.
  Remediation: Consider maintaining the established phrasing "everything else is autonomous".

[fullsend-ai-review]

🤖 Finished Review · ✅ Success · Started 9:14 PM UTC · Completed 9:27 PM UTC
Commit: e44aaeb · View workflow run →

[Roming22]

lgtm

[fullsend-ai-review]

🤖 Finished Review · ✅ Success · Started 8:26 PM UTC · Completed 8:37 PM UTC
Commit: 4b78af2 · View workflow run →

Superseded by updated review

[fullsend-ai-review]

See the review comment for full details.

[fullsend-ai-retro]

🤖 Finished Retro · ✅ Success · Started 12:39 PM UTC · Completed 12:45 PM UTC
Commit: 4b78af2 · View workflow run →

[fullsend-ai-retro]

Retro: PR #3378 — docs(vision): frame autonomy as configurable per workflow

A docs-only, 4-line change to docs/vision.md took 3 days to merge (Jul 7–10). The review agent ran 3 times, raising the same two medium findings each time despite the author explicitly addressing them. Two proposals filed as evidence for existing tracked issues.

Timeline

1. Jul 7 15:52 — ralphbean opens PR (1 file, 4 additions, 4 deletions)
2. Jul 7 15:56 — Roming22 (human) reviews and suggests minor wording change; also approves the core changes
3. Jul 7 16:04 — Review agent (run 1) raises 4 findings: terminology-consistency [medium], unsubstantiated-architecture-claim [medium], internal-consistency [medium], stylistic-consistency [low]
4. Jul 7 ~21:13 — Author pushes commit addressing the [low] stylistic-consistency finding
5. Jul 7 21:27 — Review agent (run 2) re-raises same 2 medium findings verbatim
6. Jul 7 22:37 — Author replies explaining both are intentional choices
7. Jul 8 06:48 — Roming22 approves
8. Jul 9 20:24 — Author pushes commit, responds to all outstanding threads
9. Jul 9 20:37 — Review agent (run 3) re-raises same 2 medium findings for the third time
10. Jul 9 20:53 — Author responds again ("Already addressed")
11. Jul 10 10:08 — rh-hemartin approves
12. Jul 10 12:37 — PR merged

Key observations

• Finding deduplication gap: The same terminology-consistency and unsubstantiated-architecture-claim findings were raised 3 times despite no relevant code changes between runs and explicit author responses. This is evidence for Review agent should deduplicate findings across iterations on the same PR #1013 and Review agent should honor explicit author dismissals of findings #1672.
• Vision doc false positive: The review agent flagged present tense in a vision document as "unsubstantiated claims," not understanding that vision documents intentionally use present tense for aspirational state. This is evidence for Review agent should deprioritize findings on planning/design documents #2678.
• One valuable finding: The terminology-consistency finding about "Guarded paths" vs "Guardrails" cross-doc inconsistency was genuinely useful — the author acknowledged it and planned follow-up work.
• Low finding was actionable: The [low] stylistic-consistency finding was actually addressed by the author, showing that even low-severity doc findings can be valuable.

Proposals filed

• Evidence for #1013 and #1672: same 2 medium findings repeated 3x across review iterations on PR #3378 (in fullsend-ai/fullsend)
• Evidence for #2678: review agent flagged present tense in vision document as unsubstantiated claim on PR #3378 (in fullsend-ai/fullsend)