[Code Quality] Improve logs command help text scannability

[github-actions]

Description

The gh aw logs command help text is comprehensive (~80 lines) but lacks visual hierarchy, making it difficult for users to quickly scan for relevant information. This affects a frequently-referenced command used during debugging and analysis.

Problem

The current help text is a continuous block without clear section separation, causing:

• High cognitive load for users scanning for specific information
• Difficulty distinguishing between basic usage, advanced patterns, and examples
• Important features may be overlooked in the wall of text

Suggested Changes

Restructure the Long description in pkg/cli/logs_command.go (lines 33-111) with clear section headers:

After (Improved structure):

Long: `Download workflow run logs and artifacts from GitHub Actions for agentic workflows.

BASIC USAGE
  Downloads workflow runs with artifacts and generates an overview table with aggregate
  metrics (duration, token usage, cost). Artifacts are organized by run ID.

DOWNLOADED ARTIFACTS
  - aw_info.json: Engine configuration and workflow metadata
  - safe_output.jsonl: Agent's final output (when non-empty)
  - agent_output/: Agent logs directory
  - agent-stdio.log: Standard output/error logs
  - aw.patch: Git patch of changes
  - workflow-logs/: GitHub Actions job logs
  - summary.json: Complete metrics for all runs

CAMPAIGN ORCHESTRATOR USAGE
  Pre-download logs in a workflow step, then reference the data:
  [step examples...]

LIVE TRACKING WITH PROJECT BOARDS
  Use summary.json to update campaign boards via 'update-project' safe output.
  [details...]

` + WorkflowIDExplanation + `

EXAMPLES
  # Basic Usage
  ` + string(constants.CLIExtensionPrefix) + ` logs                    # All workflows
  ...

Files Affected

• pkg/cli/logs_command.go (lines 33-111)

Success Criteria

• Help text organized into scannable sections with blank lines
• Section headers in UPPERCASE for visual distinction
• Content grouped logically (basic → advanced → examples)
• All existing examples preserved
• Reduces time to find relevant information by 50%+

Priority

High - Frequently-referenced command, improves user efficiency and productivity

Source

Extracted from User Experience Analysis discussion #12888

Quote from source:

The help text is comprehensive with ~80 lines covering 17+ example commands, but it's presented as a continuous block without visual hierarchy, making it difficult for enterprise users to quickly scan for relevant information.

Estimated Effort

30-45 minutes - Single file restructuring with no logic changes

AI generated by Discussion Task Miner - Code Quality Improvement Agent

• expires on Feb 14, 2026, 1:19 PM UTC