| name | status-writing |
| description | Write and update STATUS.md files to provide at-a-glance visibility into project health as a single source of truth. Use at project start, during weekly syncs, after major releases, or whenever project status significantly changes. Trigger phrases: 'create a status file', 'update the project status', 'what's the current state', 'document where we are', 'create a status dashboard'. |
Status Writer Skill
Version: 1.0
Created: 2026-02-04
Author: Manus AI
Purpose: To provide a structured, repeatable process for writing and updating STATUS.md files, turning project tracking into a mindful and transparent practice.
I. The Philosophy: The Ritual of Bearing Witness
A STATUS.md file is more than a report; it is a Ritual of Bearing Witness. It is a practice of radical honesty about where a project truly is—not where we wish it were, or where it is supposed to be. It is a pause to see clearly, without judgment, the current state of our work.
This ritual combats the natural tendency for entropy and confusion to creep into complex projects. It provides a single, trusted source of truth that grounds our conversations and decisions in reality. By maintaining this document with care, we cultivate transparency, accountability, and a shared understanding of our journey.
II. When to Use This Skill
- At the beginning of a new project: To establish the initial state and vision.
- At the start and end of a work session: To frame the day's work and document its outcome.
- During a weekly sync: To facilitate a high-level review of all active projects.
- Whenever there is a significant change in project status: (e.g., a new blocker emerges, a major milestone is reached).
III. The Status Update Workflow
Step 1: Locate or Create the STATUS.md File
Navigate to the root of the project repository. If a STATUS.md file does not exist, create one using the template from Section IV of this skill.
Step 2: Update the Header
Change the Last Updated date to the current date.
Step 3: Review and Update Each Section
Go through each section of the STATUS.md file and update it to reflect the current reality.
- Vision & Purpose: This should rarely change, but it is good to re-read it to stay grounded.
- Current State: This is the most important section. Update the status of each area using the emoji key (✅, 🔄, ⏸️, ❌). Add or remove items as the project evolves.
- Active Workstreams: What are you actively working on right now? Update the tasks and progress.
- Blockers & Dependencies: Be ruthlessly honest about what is preventing progress. If a blocker is resolved, remove it.
- Next Steps: What is the immediate next action? This should be concrete and actionable.
Step 4: Commit the Changes
Commit the updated STATUS.md file with a clear and descriptive commit message.
Commit Message Convention:
docs(status): Update [Project Name] status for [Date]
Example:
docs(status): Update AROMA status for 2026-02-04
IV. STATUS.md Template
# [Project Name] Project Status
**Author:** [Your Name]
**Status:** [Active & Evolving | On Hold | Complete]
**Last Updated:** [YYYY-MM-DD]
---
## 1. Vision & Purpose
> [A single, compelling sentence that captures the essence of this project.]
**Core Principles:**
- [Principle 1]
- [Principle 2]
- [Principle 3]
---
## 2. Current State
[A brief, high-level summary of the project's current phase or condition.]
| Area | Status | Notes |
| :--- | :--- | :--- |
| **[Key Area 1]** | [✅/🔄/⏸️/❌] | [Brief, relevant notes.] |
| **[Key Area 2]** | [✅/🔄/⏸️/❌] | [Brief, relevant notes.] |
| **[Key Area 3]** | [✅/🔄/⏸️/❌] | [Brief, relevant notes.] |
**Status Key:**
- ✅ **Complete:** The work is done and verified.
- 🔄 **In Progress:** Actively being worked on.
- ⏸️ **Paused:** Intentionally on hold.
- ❌ **Blocked:** Progress is halted due to a dependency or issue.
---
## 3. Active Workstreams
[What are we actively working on right now? Be specific.]
1. **[Workstream 1]:**
- **Task:** [Description of the current task.]
- **Progress:** [e.g., 75% complete, waiting for review]
2. **[Workstream 2]:**
- **Task:** [Description of the current task.]
- **Progress:** [e.g., Just started, gathering requirements]
---
## 4. Blockers & Dependencies
[What is preventing progress? Be ruthlessly honest.]
- [Description of the blocker and its impact.]
[Who is responsible for resolving this?]
[What is the next action to resolve this?]
---
[What are the immediate next actions for this project?]
[A concrete, actionable task.]
[A concrete, actionable task.]
[A concrete, actionable task.]
V. Best Practices
- Be Honest: The value of this document is its truthfulness. Do not sugarcoat bad news.
- Be Concise: Use bullet points and short sentences. This is a dashboard, not a novel.
- Use the Emoji Key: The emojis provide an instant visual summary of project health.
- Update Regularly: A stale status document is worse than no status document. Make it a habit.
- Focus on the 'What', Not the 'Who': The status is about the project, not the people. Frame blockers and issues impersonally.
