Skip to content

Add 3 philosophy framing callouts to gitkraken-desktop/agents.md at exact anchors below #90

Description

@jjsilva4

Task

Insert three HTML callout blocks into gitkraken-desktop/agents.md at the exact locations
below, then update two date lines. All wording is final — insert it exactly as written.
Do not change anything else in the file or repo.

Rules

  • Edit only gitkraken-desktop/agents.md.
  • Insert one blank line above and below each inserted block.
  • Do not modify any heading, list item, table, figure, existing callout, procedure step,
    or surrounding prose. Do not reflow or "improve" any existing text.
  • Do not edit llms.txt, llms-full.txt, or sitemap.xml.

Insertion 1 — "When to use coding agents in GitKraken Desktop" section

Find this exact line (last item of the "usually not the best choice" list):

- Need behavior that depends on a CLI that is not installed or configured

Insert after it, before the *** divider that follows:

<div class='callout callout--basic'>
  <p><strong>Why the workflow is split this way:</strong> Coding agents are strong at producing code toward a goal you define, and weaker at deciding what is worth doing or whether a result is good enough to ship. Agent Sessions View reflects that split: you choose the task and judge the output, and the agent handles the work in between.</p>
</div>

Insertion 2 — "How to monitor coding agent progress and session status" section

Find this exact line:

You can keep working in another worktree while monitoring these cards. When a session finishes, switch to that worktree to review the results.

Insert after it, before the ### How to filter and sort agent sessions heading:

<div class='callout callout--basic'>
  <p><strong>Monitoring is part of the work:</strong> When you run several sessions in parallel, your role shifts from writing each change to directing and evaluating many changes at once. The status cards show you where your attention and judgment are needed next.</p>
</div>

Insertion 3 — "Typical workflow for coding agents and worktrees" section

Find this exact line:

8. After the work is merged or no longer needed, you remove the worktree.

Insert after it, before the *** divider that follows:

<div class='callout callout--basic'>
  <p><strong>Expect more work to become practical, not less:</strong> Parallel agent sessions do not shrink your backlog. They make tasks that were previously not worth the setup cost, such as small refactors and low-priority fixes, practical to start while you stay focused on your main work.</p>
</div>

Date updates (only these two existing lines may change)

  1. In the YAML frontmatter, change last_verified: 2026-06 to last_verified: 2026-07.
  2. Change <kbd>Last updated: June 2026</kbd> to <kbd>Last updated: July 2026</kbd>.

Verification (all must pass before opening a PR)

  • grep -c "callout--basic" gitkraken-desktop/agents.md returns 6 (currently 3)
  • git diff --stat lists only gitkraken-desktop/agents.md
  • git diff shows exactly 2 removed lines (the two date lines being replaced)
  • No lines starting with #, -, or a digit were modified

Branch / PR

  • Branch: docs/agents-philosophy-callouts
  • PR body: Fixes #<this issue> plus a bulleted "Proposed Changes" list (matches
    pull_request_template.md)

Metadata

Metadata

Assignees

Labels

No labels
No labels

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions