TongyiDai/agent-value-ledger

AI's Time is Money — Agent Value Ledger

Maintain a value ledger of completed agent work using a local Excel workbook. The agent is responsible for discovering, deduplicating, estimating, and updating entries; the user only needs to review anomalies, not manually fill in each row.

Design Boundaries

• Relies solely on local Excel; no dependency on Feishu, Base, databases, or external sync services.
• The ledger records "auditable time replacement value"; estimated amounts are not expressed as cash income, profit, or guaranteed revenue.
• By default, displays conservative low values (saved_minutes_low and saved_cny_low); medium and high values are kept only as reference ranges in the Excel file.
• Only records work with a clear completion state or deliverable. Discussions, preference logs, failed attempts, repetitive maintenance, and conversations with suggestions but no output are skipped by default.
• Does not save full conversations, sensitive original text, credentials, private financial details, or unnecessary personal data; evidence only includes short titles, dates, source IDs, local paths, or deliverable types.

Workbook Structure

Prefer using the assets/agent-value-ledger-template.xlsx file provided with this skill. If the user already has a workbook, read and preserve its structure; only create missing required sheets.

• Summary: Low-value main conclusion, weekly/monthly summaries, reference ranges, low confidence, and pending review count. Entirely formula-driven.
• Task Details: One row per completed task. Time, value, confidence, evidence, and assumptions are stored in separate columns.
• Rules: Hourly rate, default costs, categories, confidence levels, and estimation boundaries. Should retain the last update time when rules are changed.
• Run Status: Last scan time, scan window, number of processed sources, recent errors, and pending review notes. Supports rescanning without relying on an additional state file.
• Run Log: Records only short events, results, and error summaries; does not include full original text.

Required fields and formulas are detailed in references/workbook-schema.md. Estimation criteria are described in references/estimation-policy.md. Redaction and evidence boundaries are defined in references/redaction-and-evidence.md.

Standard Procedure

1. Reading the Workbook and Rules

1. Find the user-specified .xlsx file; if not specified, look for agent-value-ledger.xlsx in the current working directory or configuration directory.
2. Read the Rules, Run Status, Task Details, and Summary sheets to confirm formulas, fields, and the last run state.
3. If the workbook does not exist, copy from the template to a user-specified local path; do not silently write to a personal directory.
4. Read the current date, timezone, hourly rate, and reporting policy. Do not treat the example hourly rate in the skill as the user's actual rate.

2. Scanning and Rescanning

1. Scan available local session summaries, task records, project logs, deliverable directories, and version histories.
2. Default rescan covers the last 7 calendar days to account for summaries saved after session completion; always deduplicate by task ID, source ID, and deliverable fingerprint.
3. First compile a candidate list, then determine completion status. Do not write directly to Excel while scanning.
4. Mark each candidate as accepted, skipped, or needs_review, and keep one reason.

3. Forming Task Records

Each task must include at least: task ID, work date, task title, short summary, category, source, deliverable, confidence level, three-level manual time, three-level user active time, three-level review rework time, hourly rate, allocated cost, assumptions, evidence status, and deduplication key.

Calculation formula:

saved_minutes = max(0, manual_minutes - user_active_minutes - review_minutes)
saved_cny = saved_minutes / 60 * hourly_rate_cny - allocated_cost_cny

Formulas are retained in Excel; computed values are not hardcoded. If subscription/API costs cannot be allocated, fill cost as 0 and note "subscription/API costs not allocated" in the assumptions.

4. Pre-Write Checks

• Task ID, dedup key, or deliverable fingerprint already exists: update evidence or skip; do not add duplicate value.
• Missing completion evidence: enters needs_review; not counted in the main summary.
• saved_minutes less than 0: treat as 0 and log the anomaly.
• Low value higher than medium or medium higher than high: stop writing and correct the estimate.
• Manually entered "lines of code, file count, run duration" can only serve as evidence; they are not directly equivalent to time saved.

5. Updating and Validation

1. Write to Task Details first, then let the Summary formulas recalculate.
2. Record Run Status and Run Log, including scan window, candidate count, new count, skipped count, pending review count, and error summary.
3. Re-read new rows, key summary cells, and formula error scan results.
4. If the file is unreadable, formulas have errors, sources are inaccessible, or writes fail, stop guessing; mark the failure and unverified scope in Run Log.
5. Report to the user only low-value main conclusion, actual new task count, pending review items, and blockers; do not output raw JSON or long logs.

Task Categories

Use the category table in the Rules sheet. Default categories include:

• simple_lookup_or_command: Simple query, explanation, one command
• feishu_lookup_or_schedule: Message, schedule, task, and workspace query
• doc_wiki_minutes_synthesis: Document, Wiki, meeting minutes, translation, and structure organization
• report_or_research: Research, analysis, proposal, and decision framework
• automation_or_workflow_setup: Automation, data pipeline, batch processing, deployment, and workflow setup
• coding_or_debugging: Code changes, troubleshooting, testing, release, and fixes
• local_setup_or_cleanup: Local installation, cleanup, migration, and maintenance

Security and Release Boundaries

• Redaction is required before entering a public repository: remove names, emails, phone numbers, usernames in paths, tokens, base URLs, internal domain names, company customer names, and private document titles.
• The example workbook can only use fictional tasks and example numbers; do not copy historical records from the user's actual ledger.
• Before a GitHub release, perform sensitive information scanning, Excel formula error scanning, skill structure validation, and public content review.
• GitHub release is not an automatic side effect of this skill; it is only executed when the user explicitly requests a release and completes review.

Resources

• references/workbook-schema.md: Workbook fields, formulas, and status values.
• references/estimation-policy.md: Three-level estimation, value calibration, and anti-cheat boundaries.
• references/redaction-and-evidence.md: Redaction, evidence minimization, and public release checks.
• scripts/build_template.mjs: Generate or rebuild a redacted Excel template.