Menu
Maintain product, architecture, and implementation docs — routes input, detects gaps, and interviews for completeness
Instalar com Codex ou Claude Copie este prompt, cole no Codex, Claude ou outro assistente e deixe que ele revise a página da skill e instale para você.
Baseado na classificação ocupacional SOC
Implement a feature or fix based on a Linear issue
Create well-structured Linear issues, projects, project updates, or initiatives
Validate a filed bug against the source before fixing it — verify every claim, hunt the broader class, find the contract question, and scope the outcome
Disciplined per-commit workflow with Greybeard review, build gates, and Critique loops
Engineering philosophy and work culture principles. Load this skill when making architectural decisions or to understand the team's work principles.
General coding conventions for clean, maintainable code. Always load this skill when writing or reviewing code in any language.
| name | scribe |
| description | Maintain product, architecture, and implementation docs — routes input, detects gaps, and interviews for completeness |
| tools | ["question","read","write","edit","glob","grep"] |
Use this skill to maintain documentation across multiple documents that represent different levels of abstraction. When the user provides input, analyze it and route it to the correct document. Scribe is not a passive filing system — after recording what the user provides, it actively identifies gaps, checks cross-document consistency, and asks targeted questions to strengthen the documentation.
Before processing input, locate the documentation files:
Search for existing files matching PRODUCT.md, ARCHITECTURE.md, and IMPLEMENTATION.md (case-insensitive) in:
docs/ directoryIf documents exist, use their locations. If multiple matches exist for the same type, prefer the repository root.
If no documents exist, use these defaults when creating new ones:
PRODUCT.md in repository rootARCHITECTURE.md in repository rootIMPLEMENTATION.md in repository rootProduct - Product-level documentation
Architecture - System architecture documentation
Implementation - Implementation documentation
Throughout this skill, you will use the question tool (also known as AskUserQuestion in some contexts) to interact with the user. The question tool allows you to present multiple questions with predefined options to the user.
Key mechanics:
multiple: true)When to provide context-aware options:
Example invocation:
{
"questions": [
{
"header": "Document classification",
"question": "Is 'fast and reliable' a user-facing promise or a system design requirement?",
"options": [
{
"label": "User-facing promise",
"description": "Add to PRODUCT.md like other user benefits"
},
{
"label": "System design requirement",
"description": "Add to ARCHITECTURE.md with latency targets"
},
{
"label": "Both",
"description": "It's a user promise AND a technical constraint"
}
]
},
{
"header": "Performance target",
"question": "Does 'fast' have a concrete target?",
"options": [
{
"label": "Under 5 seconds",
"description": "Similar to report generation target"
},
{
"label": "Different target",
"description": "Specify a different performance goal"
},
{
"label": "No specific target",
"description": "Keep it qualitative for now"
}
]
}
]
}
The tool returns the selected options as an array of labels (e.g., ["Both", "Under 5 seconds"]).
Before classifying input, locate and read the existing documentation files to learn project-specific vocabulary and patterns. This information will be used throughout all subsequent steps for context-aware questioning.
PRODUCT.md, ARCHITECTURE.md, and IMPLEMENTATION.md (case-insensitive) in repository root and docs/ directoryRead the user's input and determine which category it falls into. Classification is based on two sources: general heuristics and project-specific signals learned from existing documents (Step 0).
General heuristics:
Product signals:
Architecture signals:
Implementation signals:
Project-specific signals:
Read the existing documents to learn the project's vocabulary. Extract key terms, component names, and patterns that indicate document ownership. For example:
Use these learned signals alongside general heuristics. Project-specific vocabulary takes precedence when it provides a clear signal.
If the categorization is clear, proceed to update the appropriate document.
If the input is ambiguous or spans multiple categories, do not simply ask "which document?" Instead, use the question tool to interview the user and decompose the input into distinct claims that can each be routed precisely:
question tool to ask targeted questions that separate those aspects. Based on the context you have from existing documents (Step 0) and the user's input, provide relevant options that help clarify the intent.If documents have content with patterns to reference:
If documents are empty/minimal (no patterns to reference):
Read the target document to understand its current structure and content.
Determine where in the document the new content belongs:
Make the update, maintaining the document's existing style and structure.
After updating, assess whether the change is significant. A change is significant if it:
If the change is minor — extending an existing section with more detail, fixing wording, adding a clarification — skip Steps 4 and 5 and proceed directly to Step 6.
Only for significant updates.
Read the other two documents and check whether the new content implies entries that should exist in sibling documents but don't. Common patterns to look for:
If gaps are found, use the question tool to present them as a batch of 2-4 questions. Based on the context from existing documents (Step 0) and the change just made, provide specific, relevant options.
Example with existing patterns:
If you just added an export service to ARCHITECTURE.md, and PRODUCT.md has no mention of exports:
I updated ARCHITECTURE.md with the export service. I noticed some potential gaps in other documents.
Use the question tool with:
For each question the user answers, update the corresponding document before proceeding.
Only for significant updates.
Scan the updated document for weaknesses:
Use the question tool to present 2-4 probing questions as a batch. Focus on non-obvious gaps — things the user might not think to document unprompted. Based on the content just added, questions already answered in this session, and patterns from existing documentation, provide specific, contextual options.
Example with existing patterns:
If you just added an export service to ARCHITECTURE.md:
Update the document with any answers the user provides. If the user declines to answer, move on without pressing.
User fatigue consideration: If the user has declined 3 or more gap detection questions in this session, skip remaining gap detection steps unless the user explicitly requests them.
Briefly confirm what was changed and in which document. If Steps 4 or 5 resulted in additional updates, summarize those as well:
Updated ARCHITECTURE.md: added export service component under "Data Pipeline" section. Also updated PRODUCT.md: added data export as a user-facing capability (from consistency check).
These examples demonstrate how classification and the active documentation steps work. The specific terms will vary by project.
Input: "Users can export their data in multiple formats" Classification: Product (describes user-facing capability)
Input: "The export service validates permissions before generating files" Classification: Architecture (describes component responsibility and interaction)
Input: "Exports are generated as CSV using the fast-csv library" Classification: Implementation (names specific format and library)
Input: "Data export is fast and reliable" Classification: Ambiguous — has both product and architecture aspects.
Instead of asking "which document?", use the question tool to decompose. After reading existing docs (Step 0) and seeing that PRODUCT.md already mentions "reports" as a user-facing feature and ARCHITECTURE.md discusses latency targets for other services:
Use the question tool:
If the user selects "Both" and "under 5 seconds", this produces two updates:
Scenario: User adds "The notification service delivers messages through email, SMS, and push" to ARCHITECTURE.md.
After updating, scribe reads the other documents and finds that PRODUCT.md has no mention of notifications as a user-facing feature, but does mention "alerts" in a different context. IMPLEMENTATION.md describes other third-party integrations using specific provider names.
Use the question tool:
Scenario: User adds a new "Authentication" section to ARCHITECTURE.md describing token-based auth with refresh tokens.
After updating, scribe scans the section and identifies gaps. From reading ARCHITECTURE.md (Step 0), scribe notices other sections mention security constraints and timeout values. IMPLEMENTATION.md describes storage mechanisms for other sensitive data.
Use the question tool:
If the target document does not exist, use the question tool to ask the user if they want to create it, with context about what type of document it is:
Question: "The [DOCUMENT].md file does not exist. Should I create it?" Options:
If the new content contradicts existing content, use the question tool to flag it with specific options:
Question: "This conflicts with existing content in [DOCUMENT].md: '[existing content]'. How should I resolve this?" Options based on the nature of the conflict:
If the input is too broad or vague to place in a specific document, use the question tool to narrow it down:
Question: "I'm not sure where '[user input]' belongs. Can you help me place it?" Options based on what aspects you can detect: