Skip to content

Commit bd26713

Browse files
mdlinvillemdlinville
authored
Merge branch 'main' into DOCS-1383 
2 parents 66190f8 + 484fc24 commit bd26713

File tree

332 files changed

+7837
-3388
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

332 files changed

+7837
-3388
lines changed

‎.ai/README.md‎

Lines changed: 130 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,130 @@
1+
# AI resources for wandb/docs
2+
3+
This directory contains resources, prompts, and tools designed to help AI agents work effectively with the wandb/docs repository.
4+
5+
## Getting started
6+
7+
Start by reading the [system prompt](./system-prompt.md) to understand your role as a member of the W&B docs team.
8+
9+
## Directory structure
10+
11+
### `system-prompt.md`
12+
The foundational context for AI agents joining the W&B docs team. Defines your role, responsibilities, and key principles for creating documentation.
13+
14+
### `style-guide.md`
15+
Comprehensive style guide for W&B documentation. Covers formatting, punctuation, code examples, and W&B-specific conventions.
16+
17+
### `runbooks/`
18+
Standardized, task-specific instructions for AI agents performing complex operations in this repository. These runbooks ensure consistent, reliable execution of recurring tasks.
19+
20+
**Example tasks:**
21+
- Testing GitHub Actions changes
22+
- Performing large-scale refactoring
23+
- Managing release processes
24+
25+
See [runbooks/README.md](./runbooks/README.md) for detailed information.
26+
27+
### Future directories (planned)
28+
29+
#### `prompts/`
30+
System prompts and context for different types of AI interactions:
31+
- Documentation writing guidelines
32+
- Code review standards
33+
- Style and tone specifications
34+
35+
#### `tools/`
36+
Scripts and utilities that AI agents can use:
37+
- Validation scripts
38+
- Automation helpers
39+
- Analysis tools
40+
41+
#### `context/`
42+
Repository-specific context that helps AI agents understand:
43+
- Architecture decisions
44+
- Historical context
45+
- Domain-specific knowledge
46+
47+
## Usage guidelines
48+
49+
### For repository maintainers
50+
1. Keep runbooks up-to-date as processes change
51+
2. Test runbooks regularly with AI agents
52+
3. Document any repository-specific quirks or constraints
53+
4. Version control all AI resources alongside code
54+
55+
### For AI agent users
56+
1. Always check for relevant runbooks before starting complex tasks
57+
2. Provide runbooks as context to your AI agent
58+
3. Report issues or ambiguities in runbooks
59+
4. Contribute improvements based on your experience
60+
61+
## Collaboration guidelines
62+
63+
When working with human and AI teammates on documentation changes:
64+
65+
### Before creating a PR
66+
- **Feature branches**: Push feature branches to collaborate with others before opening a PR.
67+
- **Branch naming**: Use descriptive names that indicate the purpose (for example, `fix/broken-links-automation-guide`).
68+
69+
### Creating pull requests
70+
1. **Start with draft PRs**: Create a draft pull request initially. This won't request reviews and can't be merged accidentally.
71+
2. **Wait for tests**: Ensure all PR tests pass before marking as ready for review.
72+
3. **Coordinate with humans**: The human coordinating the work should verify the changes meet requirements before marking the PR ready for review. A human should ultimately merge a PR, not an agent.
73+
74+
### PR titles and descriptions
75+
- **Be meaningful but concise**: Write clear titles that describe what changed.
76+
- **Link relevant context**: Include:
77+
- JIRA IDs (for example, `DOCS-1234`)
78+
- GitHub issue IDs (for example, `#456`)
79+
- Related PRs for additional context
80+
- **Add before/after comparison**: When applicable, include:
81+
- Links to the current live documentation
82+
- Links to the PR's HTML preview showing the changes
83+
- Brief description of what changed and why
84+
85+
### Example PR description
86+
```
87+
## Description
88+
89+
Updates AI agent style guide to improve accessibility and code quality.
90+
91+
The style guide now provides clearer guidance for AI agents creating documentation:
92+
- Added accessibility guidelines (no emojis)
93+
- Added code example best practices
94+
- Created runbook template
95+
96+
### Before/After
97+
- Live docs: https://docs.wandb.ai/guides/ai-resources
98+
- PR preview: https://preview-12345.pages.dev/guides/ai-resources
99+
100+
## Related issues
101+
102+
- Fixes DOCS-1234
103+
- Related to #456
104+
```
105+
106+
## Best practices
107+
108+
1. **Capture knowledge immediately**: After completing any complex task with an AI agent, ask them to draft a runbook while the details are fresh
109+
2. **Specificity**: Be explicit about every step, assumption, and requirement
110+
3. **Adaptability**: Include variations for common scenarios
111+
4. **Safety**: Always include cleanup steps and error handling
112+
5. **Testing**: Verify runbooks work with multiple AI providers
113+
6. **Maintenance**: Update runbooks when workflows or tools change
114+
7. **Iterative improvement**: Have agents review and improve existing runbooks based on their experience
115+
116+
## Contributing
117+
118+
When adding AI resources:
119+
120+
1. Follow existing naming conventions and structure
121+
2. Include comprehensive documentation
122+
3. Test with at least one AI agent
123+
4. Update relevant README files
124+
5. Consider security implications of any shared context
125+
126+
## Security notes
127+
128+
- Never include sensitive information (API keys, passwords, etc.)
129+
- Be cautious about exposing internal URLs or infrastructure details
130+
- Review all contributions for potential security risks

‎.ai/runbooks/README.md‎

Lines changed: 92 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,92 @@
1+
# AI agent runbooks
2+
3+
This directory contains standardized runbooks (task-specific prompts) for AI agents working with the wandb/docs repository.
4+
5+
## What are AI runbooks?
6+
7+
AI runbooks are detailed, step-by-step instructions designed to help AI agents perform complex, recurring tasks consistently and correctly. They include:
8+
9+
- **Context and constraints** specific to the task
10+
- **Prerequisites** the agent should gather from users
11+
- **Step-by-step procedures** with exact commands
12+
- **Common issues and solutions**
13+
- **Cleanup instructions**
14+
15+
## Available runbooks
16+
17+
### [test-github-action-changes.md](./test-github-action-changes.md)
18+
Tests changes to GitHub Actions workflows using a fork, particularly for workflows that depend on Cloudflare Pages deployments.
19+
20+
**Use cases:**
21+
- Testing dependency upgrades (for example, Dependabot PRs)
22+
- Verifying workflow functionality changes
23+
- Debugging GitHub Actions issues
24+
25+
### [TEMPLATE.md](./TEMPLATE.md)
26+
A template for creating new runbooks. Copy this file and fill in the sections to create standardized, AI-friendly runbooks.
27+
28+
## How to use these runbooks
29+
30+
### For humans
31+
1. Provide the runbook to your AI agent as context
32+
2. Answer any prerequisite questions the agent asks
33+
3. Follow along as the agent executes the steps
34+
4. Complete any manual steps the agent cannot perform
35+
36+
### For AI agents
37+
1. Read the entire runbook before starting
38+
2. Gather all prerequisites from the user
39+
3. Follow the steps exactly, adapting only where explicitly noted
40+
4. Ask for clarification if any step is unclear
41+
5. Clean up all temporary resources after completion
42+
43+
## Creating new runbooks
44+
45+
### Best practice: Agent-first authoring
46+
The most effective runbooks are often created by having an AI agent write the first draft immediately after completing a complex task together. At the end of any challenging interactive task, consider asking your agent:
47+
48+
> "Based on what we just did together, please create a runbook that would help another agent perform this same task in the future. Include all the context, gotchas, and workarounds we discovered."
49+
50+
This captures the knowledge while it's fresh and ensures nothing important is forgotten.
51+
52+
### When creating a new runbook
53+
54+
1. **Start with the template**: Copy [TEMPLATE.md](./TEMPLATE.md) as a starting point for consistency
55+
56+
2. **Follow the template structure**:
57+
- Requirements
58+
- Agent Prerequisites
59+
- Task Overview
60+
- Context and Constraints
61+
- Step-by-Step Process
62+
- Common Issues and Solutions
63+
- Cleanup Instructions
64+
65+
3. **Make it agent-friendly**:
66+
- Use placeholders like `<username>` that agents should replace
67+
- Include explicit instructions for what agents should ask users
68+
- Provide fallback procedures when agents lack permissions
69+
70+
4. **Include all necessary context**:
71+
- Repository-specific constraints
72+
- Tool-specific limitations
73+
- Security considerations
74+
75+
5. **Test the runbook**:
76+
- Have an AI agent follow it exactly
77+
- Note any ambiguities or missing steps
78+
- Iterate until the process is smooth
79+
80+
6. **Get an agent review**:
81+
- Ask an AI agent to review the runbook for agent-friendliness
82+
- Example prompt: "Please review this runbook and suggest improvements to make it more useful for AI agents. Focus on clarity, completeness, and removing ambiguity."
83+
- Incorporate the suggested improvements
84+
85+
## Contributing
86+
87+
To add or improve runbooks:
88+
89+
1. Follow the existing format and style
90+
2. Test thoroughly with an AI agent
91+
3. Include real examples where helpful
92+
4. Update this README with your new runbook

‎.ai/runbooks/TEMPLATE.md‎

Lines changed: 104 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,104 @@
1+
# Agent prompt: [Task title]
2+
3+
## Requirements
4+
List any access requirements or prerequisites that must be met before starting this task:
5+
- [ ] Required system access (for example, W&B employee access).
6+
- [ ] Required permissions (for example, repository write access).
7+
- [ ] Required tools or dependencies.
8+
9+
## Agent prerequisites
10+
Information to gather from the user before starting:
11+
1. **[Required info 1]** - Why it's needed
12+
2. **[Required info 2]** - Why it's needed
13+
3. **[Optional info]** - When/why it might be needed
14+
15+
## Task overview
16+
Brief description of what this runbook accomplishes and when to use it.
17+
18+
> **Note**: Any important context or limitations users should know upfront.
19+
20+
## Context and constraints
21+
22+
### System/tool limitations
23+
- Limitation 1 and how it affects the task
24+
- Limitation 2 and workarounds if any
25+
26+
### Important context
27+
- Key background information
28+
- Common gotchas or edge cases
29+
- Security considerations
30+
31+
## Step-by-step process
32+
33+
### 1. [First major step]
34+
Description of what this step accomplishes.
35+
36+
```bash
37+
# Example commands
38+
command --with-flags
39+
```
40+
41+
**Expected result**: What should happen after this step.
42+
43+
### 2. [Second major step]
44+
Description and any decision points.
45+
46+
**Agent note**: Special instructions for AI agents, such as:
47+
- When to ask the user for clarification
48+
- Fallback procedures if lacking permissions
49+
- How to handle common variations
50+
51+
### 3. [Continue with remaining steps...]
52+
53+
## Verification and testing
54+
55+
Expected outcomes:
56+
- ✓ Success indicator 1
57+
- ✓ Success indicator 2
58+
- ✗ Common failure indicator and what it means
59+
60+
### How to verify success
61+
1. Check that...
62+
2. Confirm that...
63+
3. Test by...
64+
65+
## Common issues and solutions
66+
67+
### Issue: [Common problem 1]
68+
- **Symptoms**: How this issue manifests
69+
- **Cause**: Why it happens
70+
- **Solution**: Step-by-step fix
71+
72+
### Issue: [Common problem 2]
73+
- **Symptoms**:
74+
- **Cause**:
75+
- **Solution**:
76+
77+
## Cleanup instructions
78+
79+
After completing the task:
80+
1. Remove any temporary files/branches.
81+
2. Reset any modified configurations.
82+
3. Document any permanent changes made.
83+
84+
```bash
85+
# Example cleanup commands
86+
git branch -D temp-branch-name
87+
rm -f temporary-files
88+
```
89+
90+
## Checklist
91+
92+
Summary checklist for the entire process:
93+
- [ ] Met all requirements.
94+
- [ ] Gathered necessary information from user.
95+
- [ ] Completed step 1: [Brief description].
96+
- [ ] Completed step 2: [Brief description].
97+
- [ ] Verified results.
98+
- [ ] Cleaned up temporary resources.
99+
- [ ] Documented any permanent changes.
100+
101+
## Notes
102+
- Additional tips or context.
103+
- Links to related documentation.
104+
- When to use alternative approaches.

0 commit comments

Comments
 (0)