Workspace Audit And Reporting

Purpose

This guideline consolidates the old read-only audit and status-report role. It helps Agents diagnose workspace structure, task quality, content health, and delivery state without silently changing files.

Audits are read-only unless the user has authorized the repair scope through guidelines/proposal-and-dry-run.

Agent Skill

When To Use

Use this skill when the user asks for:

• workspace health, schema, link, or placement diagnosis;
• task metadata, readiness, blocker, owner, or board consistency checks;
• project status, release readiness, delivery progress, or knowledge-base report;
• stale, contradictory, duplicate, orphaned, or localized-only content detection;
• dry-run repair suggestions without applying them.

Bootstrap

Follow the common bootstrap in skills get workspace-operations (guidelines/forma-workspace-operations) using this repository's CLI invocation. Reuse current results and load only the guideline needed for this request.

Run cargo run -q -p forma-cli -- check --json for validation findings. Inspect affected entries; for Task audits also list candidate Tasks and render the board. Reuse unchanged results.

Audit Rules

• Separate machine diagnostics from human judgment.
• Separate field-based, board-based, link-based, git-based, test-based, and inferred evidence.
• Treat task status as board membership and readiness as executability.
• Treat proposals as unaccepted until their status and related canonical target show acceptance.
• Treat repository-excluded local files as workflow-local context unless the user selected them for review. Do not claim that Forma paths provide privacy.
• Report stale or contradictory claims with source paths instead of choosing silently.
• Apply repairs only within user-authorized scope, using the preview decision in guidelines/proposal-and-dry-run.

Report Shape

Use the smallest report that answers the question:

• Scope: spaces, views, files, or task set inspected.
• Evidence: commands and key files used.
• Findings: ordered by impact, with file paths.
• Dry-run fixes: concrete repairs that would require approval.
• Requires judgment: decisions the Agent cannot make safely.
• Residual risk: checks not run or evidence not available.

For status reports, include Reliability: verified, partial, or inferred.

Handoff To Write Work

When an audit finds repair work:

1. Summarize the smallest coherent fix.
2. Point to the target guideline: guidelines/content-maintenance, guidelines/task-selection, or guidelines/proposal-and-dry-run.
3. Continue if the user already authorized the repair scope; otherwise present the concrete repair for approval.

Completion Criteria

Complete the audit only when scope, evidence class, impact-ordered findings, reliability, proposed repairs, judgment boundaries, and checks not run are explicit, with no unapproved file changes.