Initial commit
This commit is contained in:
Zhongwei Li
@@ -0,0 +1,937 @@
|
||||
# Mandatory Quality Standards
|
||||
|
||||
## Fundamental Principles
|
||||
|
||||
**Production-Ready, Not Prototype**
|
||||
- Code must work without modifications
|
||||
- Doesn't need "now implement X"
|
||||
- Can be used immediately
|
||||
|
||||
**Functional, Not Placeholder**
|
||||
- Complete code in all functions
|
||||
- No TODO, pass, NotImplementedError
|
||||
- Robust error handling
|
||||
|
||||
**Useful, Not Generic**
|
||||
- Specific and detailed content
|
||||
- Concrete examples, not abstract
|
||||
- Not just external links
|
||||
|
||||
---
|
||||
|
||||
## Standards by File Type
|
||||
|
||||
### Python Scripts
|
||||
|
||||
#### ✅ MANDATORY
|
||||
|
||||
**1. Complete structure**:
|
||||
```python
|
||||
#!/usr/bin/env python3
|
||||
"""Module docstring"""
|
||||
|
||||
# Imports
|
||||
import ...
|
||||
|
||||
# Constants
|
||||
CONST = value
|
||||
|
||||
# Classes/Functions
|
||||
class/def ...
|
||||
|
||||
# Main
|
||||
def main():
|
||||
...
|
||||
|
||||
if __name__ == "__main__":
|
||||
main()
|
||||
```
|
||||
|
||||
**2. Docstrings**:
|
||||
- Module docstring: 3-5 lines
|
||||
- Class docstring: Description + Example
|
||||
- Method docstring: Args, Returns, Raises, Example
|
||||
|
||||
**3. Type hints**:
|
||||
```python
|
||||
def function(param1: str, param2: int = 10) -> Dict[str, Any]:
|
||||
...
|
||||
```
|
||||
|
||||
**4. Error handling**:
|
||||
```python
|
||||
try:
|
||||
result = risky_operation()
|
||||
except SpecificError as e:
|
||||
# Handle specifically
|
||||
log_error(e)
|
||||
raise CustomError(f"Context: {e}")
|
||||
```
|
||||
|
||||
**5. Validations**:
|
||||
```python
|
||||
def process(data: Dict) -> pd.DataFrame:
|
||||
# Validate input
|
||||
if not data:
|
||||
raise ValueError("Data cannot be empty")
|
||||
|
||||
if 'required_field' not in data:
|
||||
raise ValueError("Missing required field")
|
||||
|
||||
# Process
|
||||
...
|
||||
|
||||
# Validate output
|
||||
assert len(result) > 0, "Result cannot be empty"
|
||||
assert result['value'].notna().all(), "No null values allowed"
|
||||
|
||||
return result
|
||||
```
|
||||
|
||||
**6. Appropriate logging**:
|
||||
```python
|
||||
import logging
|
||||
|
||||
logger = logging.getLogger(__name__)
|
||||
|
||||
def fetch_data():
|
||||
logger.info("Fetching data from API...")
|
||||
# ...
|
||||
logger.debug(f"Received {len(data)} records")
|
||||
# ...
|
||||
logger.error(f"API error: {e}")
|
||||
```
|
||||
|
||||
#### ❌ FORBIDDEN
|
||||
|
||||
```python
|
||||
# ❌ DON'T DO THIS:
|
||||
|
||||
def analyze():
|
||||
# TODO: implement analysis
|
||||
pass
|
||||
|
||||
def process(data): # ❌ No type hints
|
||||
# ❌ No docstring
|
||||
result = data # ❌ No real logic
|
||||
return result # ❌ No validation
|
||||
|
||||
def fetch_api(url):
|
||||
response = requests.get(url) # ❌ No timeout
|
||||
return response.json() # ❌ No error handling
|
||||
```
|
||||
|
||||
#### ✅ DO THIS:
|
||||
|
||||
```python
|
||||
def analyze_yoy(df: pd.DataFrame, commodity: str, year1: int, year2: int) -> Dict:
|
||||
"""
|
||||
Perform year-over-year analysis
|
||||
|
||||
Args:
|
||||
df: DataFrame with parsed data
|
||||
commodity: Commodity name (e.g., "CORN")
|
||||
year1: Current year
|
||||
year2: Previous year
|
||||
|
||||
Returns:
|
||||
Dict with keys:
|
||||
- production_current: float
|
||||
- production_previous: float
|
||||
- change_percent: float
|
||||
- interpretation: str
|
||||
|
||||
Raises:
|
||||
ValueError: If data not found for specified years
|
||||
DataQualityError: If data fails validation
|
||||
|
||||
Example:
|
||||
>>> analyze_yoy(df, "CORN", 2023, 2022)
|
||||
{'production_current': 15.3, 'change_percent': 11.7, ...}
|
||||
"""
|
||||
# Validate inputs
|
||||
if commodity not in df['commodity'].unique():
|
||||
raise ValueError(f"Commodity {commodity} not found in data")
|
||||
|
||||
# Filter data
|
||||
df1 = df[(df['commodity'] == commodity) & (df['year'] == year1)]
|
||||
df2 = df[(df['commodity'] == commodity) & (df['year'] == year2)]
|
||||
|
||||
if len(df1) == 0 or len(df2) == 0:
|
||||
raise ValueError(f"Data not found for {commodity} in {year1} or {year2}")
|
||||
|
||||
# Extract values
|
||||
prod1 = df1['production'].iloc[0]
|
||||
prod2 = df2['production'].iloc[0]
|
||||
|
||||
# Calculate
|
||||
change = prod1 - prod2
|
||||
change_pct = (change / prod2) * 100
|
||||
|
||||
# Interpret
|
||||
if abs(change_pct) < 2:
|
||||
interpretation = "stable"
|
||||
elif change_pct > 10:
|
||||
interpretation = "significant_increase"
|
||||
elif change_pct > 2:
|
||||
interpretation = "moderate_increase"
|
||||
elif change_pct < -10:
|
||||
interpretation = "significant_decrease"
|
||||
else:
|
||||
interpretation = "moderate_decrease"
|
||||
|
||||
# Return
|
||||
return {
|
||||
"commodity": commodity,
|
||||
"production_current": round(prod1, 1),
|
||||
"production_previous": round(prod2, 1),
|
||||
"change_absolute": round(change, 1),
|
||||
"change_percent": round(change_pct, 1),
|
||||
"interpretation": interpretation
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### SKILL.md
|
||||
|
||||
#### ✅ MANDATORY
|
||||
|
||||
**1. Valid frontmatter**:
|
||||
```yaml
|
||||
---
|
||||
name: agent-name
|
||||
description: [150-250 words with keywords]
|
||||
---
|
||||
```
|
||||
|
||||
**2. Size**: 5000-7000 words
|
||||
|
||||
**3. Mandatory sections**:
|
||||
- When to use (specific triggers)
|
||||
- Data source (detailed API)
|
||||
- Workflows (complete step-by-step)
|
||||
- Scripts (each one explained)
|
||||
- Analyses (methodologies)
|
||||
- Errors (complete handling)
|
||||
- Validations (mandatory)
|
||||
- Keywords (complete list)
|
||||
- Examples (5+ complete)
|
||||
|
||||
**4. Detailed workflows**:
|
||||
|
||||
✅ **GOOD**:
|
||||
```markdown
|
||||
### Workflow: YoY Comparison
|
||||
|
||||
1. **Identify question parameters**
|
||||
- Commodity: [extract from question]
|
||||
- Years: Current vs previous (or specified)
|
||||
|
||||
2. **Fetch data**
|
||||
```bash
|
||||
python scripts/fetch_nass.py \
|
||||
--commodity CORN \
|
||||
--years 2023,2022 \
|
||||
--output data/raw/corn_2023_2022.json
|
||||
```
|
||||
|
||||
3. **Parse**
|
||||
```bash
|
||||
python scripts/parse_nass.py \
|
||||
--input data/raw/corn_2023_2022.json \
|
||||
--output data/processed/corn.csv
|
||||
```
|
||||
|
||||
4. **Analyze**
|
||||
```bash
|
||||
python scripts/analyze_nass.py \
|
||||
--input data/processed/corn.csv \
|
||||
--analysis yoy \
|
||||
--commodity CORN \
|
||||
--year1 2023 \
|
||||
--year2 2022 \
|
||||
--output data/analysis/corn_yoy.json
|
||||
```
|
||||
|
||||
5. **Interpret results**
|
||||
|
||||
File `data/analysis/corn_yoy.json` contains:
|
||||
```json
|
||||
{
|
||||
"production_current": 15.3,
|
||||
"change_percent": 11.7,
|
||||
"interpretation": "significant_increase"
|
||||
}
|
||||
```
|
||||
|
||||
Respond to user:
|
||||
"Corn production grew 11.7% in 2023..."
|
||||
```
|
||||
|
||||
❌ **BAD**:
|
||||
```markdown
|
||||
### Workflow: Comparison
|
||||
|
||||
1. Get data
|
||||
2. Compare
|
||||
3. Return result
|
||||
```
|
||||
|
||||
**5. Complete examples**:
|
||||
|
||||
✅ **GOOD**:
|
||||
```markdown
|
||||
### Example 1: YoY Comparison
|
||||
|
||||
**Question**: "How's corn production compared to last year?"
|
||||
|
||||
**Executed flow**:
|
||||
[Specific commands with outputs]
|
||||
|
||||
**Generated answer**:
|
||||
"Corn production in 2023 is 15.3 billion bushels,
|
||||
growth of 11.7% vs 2022 (13.7 billion). Growth
|
||||
comes mainly from area increase (+8%) with stable yield."
|
||||
```
|
||||
|
||||
❌ **BAD**:
|
||||
```markdown
|
||||
### Example: Comparison
|
||||
|
||||
User asks about comparison. Agent compares and responds.
|
||||
```
|
||||
|
||||
#### ❌ FORBIDDEN
|
||||
|
||||
- Empty sections
|
||||
- "See documentation"
|
||||
- Workflows without specific commands
|
||||
- Generic examples
|
||||
|
||||
---
|
||||
|
||||
### References
|
||||
|
||||
#### ✅ MANDATORY
|
||||
|
||||
**1. Useful and self-contained content**:
|
||||
|
||||
✅ **GOOD** (references/api-guide.md):
|
||||
```markdown
|
||||
## Endpoint: Get Production Data
|
||||
|
||||
**URL**: `GET https://quickstats.nass.usda.gov/api/api_GET/`
|
||||
|
||||
**Parameters**:
|
||||
- `commodity_desc`: Commodity name
|
||||
- Example: "CORN", "SOYBEANS"
|
||||
- Case-sensitive
|
||||
- `year`: Desired year
|
||||
- Example: 2023
|
||||
- Range: 1866-present
|
||||
|
||||
**Complete request example**:
|
||||
```bash
|
||||
curl -H "X-Api-Key: YOUR_KEY" \
|
||||
"https://quickstats.nass.usda.gov/api/api_GET/?commodity_desc=CORN&year=2023&format=JSON"
|
||||
```
|
||||
|
||||
**Expected response**:
|
||||
```json
|
||||
{
|
||||
"data": [
|
||||
{
|
||||
"year": 2023,
|
||||
"commodity_desc": "CORN",
|
||||
"value": "15,300,000,000",
|
||||
"unit_desc": "BU"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**Important fields**:
|
||||
- `value`: Comes as STRING with commas
|
||||
- Solution: `value.replace(',', '')`
|
||||
- Convert to float after
|
||||
```
|
||||
|
||||
❌ **BAD**:
|
||||
```markdown
|
||||
## API Endpoint
|
||||
|
||||
For details on how to use the API, consult the official documentation at:
|
||||
https://quickstats.nass.usda.gov/api
|
||||
|
||||
[End of file]
|
||||
```
|
||||
|
||||
**2. Adequate size**:
|
||||
- API guide: 1500-2000 words
|
||||
- Analysis methods: 2000-3000 words
|
||||
- Troubleshooting: 1000-1500 words
|
||||
|
||||
**3. Concrete examples**:
|
||||
- Always include examples with real values
|
||||
- Executable code blocks
|
||||
- Expected outputs
|
||||
|
||||
#### ❌ FORBIDDEN
|
||||
|
||||
- "For more information, see [link]"
|
||||
- Sections with only 2-3 lines
|
||||
- Lists without details
|
||||
- Circular references ("see other doc that sees other doc")
|
||||
|
||||
---
|
||||
|
||||
### Assets (Configs)
|
||||
|
||||
#### ✅ MANDATORY
|
||||
|
||||
**1. Syntactically valid JSON**:
|
||||
```bash
|
||||
# ALWAYS validate:
|
||||
python -c "import json; json.load(open('config.json'))"
|
||||
```
|
||||
|
||||
**2. Real values**:
|
||||
|
||||
✅ **GOOD**:
|
||||
```json
|
||||
{
|
||||
"api": {
|
||||
"base_url": "https://quickstats.nass.usda.gov/api",
|
||||
"api_key_env": "NASS_API_KEY",
|
||||
"_instructions": "Get free API key from: https://quickstats.nass.usda.gov/api#registration",
|
||||
"rate_limit_per_day": 1000,
|
||||
"timeout_seconds": 30
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
❌ **BAD**:
|
||||
```json
|
||||
{
|
||||
"api": {
|
||||
"base_url": "YOUR_API_URL_HERE",
|
||||
"api_key": "YOUR_KEY_HERE"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**3. Inline comments** (using `_comment` or `_note`):
|
||||
```json
|
||||
{
|
||||
"_comment": "Differentiated TTL by data type",
|
||||
"cache": {
|
||||
"ttl_historical_days": 365,
|
||||
"_note_historical": "Historical data doesn't change",
|
||||
"ttl_current_days": 7,
|
||||
"_note_current": "Current year data may be revised"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### README.md
|
||||
|
||||
#### ✅ MANDATORY
|
||||
|
||||
**1. Complete installation instructions**:
|
||||
|
||||
✅ **GOOD**:
|
||||
```markdown
|
||||
## Installation
|
||||
|
||||
### 1. Get API Key (Free)
|
||||
|
||||
1. Access https://quickstats.nass.usda.gov/api#registration
|
||||
2. Fill form:
|
||||
- Name: [your name]
|
||||
- Email: [your email]
|
||||
- Purpose: "Personal research"
|
||||
3. Click "Submit"
|
||||
4. You'll receive email with API key in ~1 minute
|
||||
5. Key format: `A1B2C3D4-E5F6-G7H8-I9J0-K1L2M3N4O5P6`
|
||||
|
||||
### 2. Configure Environment
|
||||
|
||||
**Option A - Export** (temporary):
|
||||
```bash
|
||||
export NASS_API_KEY="your_key_here"
|
||||
```
|
||||
|
||||
**Option B - .bashrc/.zshrc** (permanent):
|
||||
```bash
|
||||
echo 'export NASS_API_KEY="your_key_here"' >> ~/.bashrc
|
||||
source ~/.bashrc
|
||||
```
|
||||
|
||||
**Option C - .env file** (per project):
|
||||
```bash
|
||||
echo "NASS_API_KEY=your_key_here" > .env
|
||||
```
|
||||
|
||||
### 3. Install Dependencies
|
||||
|
||||
```bash
|
||||
cd nass-usda-agriculture
|
||||
pip install -r requirements.txt
|
||||
```
|
||||
|
||||
Requirements:
|
||||
- requests
|
||||
- pandas
|
||||
- numpy
|
||||
```
|
||||
|
||||
❌ **BAD**:
|
||||
```markdown
|
||||
## Installation
|
||||
|
||||
1. Get API key from the official website
|
||||
2. Configure environment
|
||||
3. Install dependencies
|
||||
4. Done!
|
||||
```
|
||||
|
||||
**2. Concrete usage examples**:
|
||||
|
||||
✅ **GOOD**:
|
||||
```markdown
|
||||
## Examples
|
||||
|
||||
### Example 1: Current Production
|
||||
|
||||
```
|
||||
You: "What's US corn production in 2023?"
|
||||
|
||||
Claude: "Corn production in 2023 was 15.3 billion
|
||||
bushels (389 million metric tons)..."
|
||||
```
|
||||
|
||||
### Example 2: YoY Comparison
|
||||
|
||||
```
|
||||
You: "Compare soybeans this year vs last year"
|
||||
|
||||
Claude: "Soybean production in 2023 is 2.6% below 2022:
|
||||
- 2023: 4.165 billion bushels
|
||||
- 2022: 4.276 billion bushels
|
||||
- Drop from area (-4.5%), yield improved (+0.8%)"
|
||||
```
|
||||
|
||||
[3-5 more examples]
|
||||
```
|
||||
|
||||
❌ **BAD**:
|
||||
```markdown
|
||||
## Usage
|
||||
|
||||
Ask questions about agriculture and the agent will respond.
|
||||
```
|
||||
|
||||
**3. Specific troubleshooting**:
|
||||
|
||||
✅ **GOOD**:
|
||||
```markdown
|
||||
### Error: "NASS_API_KEY environment variable not found"
|
||||
|
||||
**Cause**: API key not configured
|
||||
|
||||
**Step-by-step solution**:
|
||||
1. Verify key was obtained: https://...
|
||||
2. Configure environment:
|
||||
```bash
|
||||
export NASS_API_KEY="your_key_here"
|
||||
```
|
||||
3. Verify:
|
||||
```bash
|
||||
echo $NASS_API_KEY
|
||||
```
|
||||
4. Should show your key
|
||||
5. If doesn't work, restart terminal
|
||||
|
||||
**Still not working?**
|
||||
- Check for extra spaces in key
|
||||
- Verify key hasn't expired (validity: 1 year)
|
||||
- Re-generate key if needed
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Quality Checklist
|
||||
|
||||
### Per Python Script
|
||||
|
||||
- [ ] Shebang: `#!/usr/bin/env python3`
|
||||
- [ ] Module docstring (3-5 lines)
|
||||
- [ ] Organized imports (stdlib, 3rd party, local)
|
||||
- [ ] Constants at top (if applicable)
|
||||
- [ ] Type hints in all public functions
|
||||
- [ ] Docstrings in classes (description + attributes + example)
|
||||
- [ ] Docstrings in methods (Args, Returns, Raises, Example)
|
||||
- [ ] Error handling for risky operations
|
||||
- [ ] Input validations
|
||||
- [ ] Output validations
|
||||
- [ ] Appropriate logging
|
||||
- [ ] Main function with argparse
|
||||
- [ ] if __name__ == "__main__"
|
||||
- [ ] Functional code (no TODO/pass)
|
||||
- [ ] Valid syntax (test: `python -m py_compile script.py`)
|
||||
|
||||
### Per SKILL.md
|
||||
|
||||
- [ ] Frontmatter with name and description
|
||||
- [ ] Description 150-250 characters with keywords
|
||||
- [ ] Size 5000+ words
|
||||
- [ ] "When to Use" section with specific triggers
|
||||
- [ ] "Data Source" section detailed
|
||||
- [ ] Step-by-step workflows with commands
|
||||
- [ ] Scripts explained individually
|
||||
- [ ] Analyses documented (objective, methodology)
|
||||
- [ ] Errors handled (all expected)
|
||||
- [ ] Validations listed
|
||||
- [ ] Performance/cache explained
|
||||
- [ ] Complete keywords
|
||||
- [ ] Complete examples (5+)
|
||||
|
||||
### Per Reference File
|
||||
|
||||
- [ ] 1000+ words
|
||||
- [ ] Useful content (not just links)
|
||||
- [ ] Concrete examples with real values
|
||||
- [ ] Executable code blocks
|
||||
- [ ] Well structured (headings, lists)
|
||||
- [ ] No empty sections
|
||||
- [ ] No "TODO: write"
|
||||
|
||||
### Per Asset (Config)
|
||||
|
||||
- [ ] Syntactically valid JSON (validate!)
|
||||
- [ ] Real values (not "YOUR_X_HERE" without context)
|
||||
- [ ] Inline comments (_comment, _note)
|
||||
- [ ] Instructions for values user must fill
|
||||
- [ ] Logical and organized structure
|
||||
|
||||
### Per README.md
|
||||
|
||||
- [ ] Step-by-step installation
|
||||
- [ ] How to get API key (detailed)
|
||||
- [ ] How to configure (3 options)
|
||||
- [ ] How to install dependencies
|
||||
- [ ] How to install in Claude Code
|
||||
- [ ] Usage examples (5+)
|
||||
- [ ] Troubleshooting (10+ problems)
|
||||
- [ ] License
|
||||
- [ ] Contact/contribution (if applicable)
|
||||
|
||||
### Complete Agent
|
||||
|
||||
- [ ] DECISIONS.md documents all choices
|
||||
- [ ] **VERSION** file created (e.g. 1.0.0)
|
||||
- [ ] **CHANGELOG.md** created with complete v1.0.0 entry
|
||||
- [ ] **INSTALACAO.md** with complete didactic tutorial
|
||||
- [ ] **comprehensive_{domain}_report()** implemented
|
||||
- [ ] marketplace.json with version field
|
||||
- [ ] 18+ files created
|
||||
- [ ] ~1500+ lines of Python code
|
||||
- [ ] ~10,000+ words of documentation
|
||||
- [ ] 2+ configs
|
||||
- [ ] requirements.txt
|
||||
- [ ] .gitignore (if needed)
|
||||
- [ ] No placeholder/TODO
|
||||
- [ ] Valid syntax (Python, JSON, YAML)
|
||||
- [ ] Ready to use (production-ready)
|
||||
|
||||
---
|
||||
|
||||
## Quality Examples
|
||||
|
||||
### Example: Error Handling
|
||||
|
||||
❌ **BAD**:
|
||||
```python
|
||||
def fetch(url):
|
||||
return requests.get(url).json()
|
||||
```
|
||||
|
||||
✅ **GOOD**:
|
||||
```python
|
||||
def fetch(url: str, timeout: int = 30) -> Dict:
|
||||
"""
|
||||
Fetch data from URL with error handling
|
||||
|
||||
Args:
|
||||
url: URL to fetch
|
||||
timeout: Timeout in seconds
|
||||
|
||||
Returns:
|
||||
JSON response as dict
|
||||
|
||||
Raises:
|
||||
NetworkError: If connection fails
|
||||
TimeoutError: If request times out
|
||||
APIError: If API returns error
|
||||
"""
|
||||
try:
|
||||
response = requests.get(url, timeout=timeout)
|
||||
response.raise_for_status()
|
||||
|
||||
data = response.json()
|
||||
|
||||
if 'error' in data:
|
||||
raise APIError(f"API error: {data['error']}")
|
||||
|
||||
return data
|
||||
|
||||
except requests.Timeout:
|
||||
raise TimeoutError(f"Request timed out after {timeout}s")
|
||||
|
||||
except requests.ConnectionError as e:
|
||||
raise NetworkError(f"Connection failed: {e}")
|
||||
|
||||
except requests.HTTPError as e:
|
||||
if e.response.status_code == 429:
|
||||
raise RateLimitError("Rate limit exceeded")
|
||||
else:
|
||||
raise APIError(f"HTTP {e.response.status_code}: {e}")
|
||||
```
|
||||
|
||||
### Example: Validations
|
||||
|
||||
❌ **BAD**:
|
||||
```python
|
||||
def parse(data):
|
||||
df = pd.DataFrame(data)
|
||||
return df
|
||||
```
|
||||
|
||||
✅ **GOOD**:
|
||||
```python
|
||||
def parse(data: List[Dict]) -> pd.DataFrame:
|
||||
"""Parse and validate data"""
|
||||
|
||||
# Validate input
|
||||
if not data:
|
||||
raise ValueError("Data cannot be empty")
|
||||
|
||||
if not isinstance(data, list):
|
||||
raise TypeError(f"Expected list, got {type(data)}")
|
||||
|
||||
# Parse
|
||||
df = pd.DataFrame(data)
|
||||
|
||||
# Validate schema
|
||||
required_cols = ['year', 'commodity', 'value']
|
||||
missing = set(required_cols) - set(df.columns)
|
||||
if missing:
|
||||
raise ValueError(f"Missing required columns: {missing}")
|
||||
|
||||
# Validate types
|
||||
df['year'] = pd.to_numeric(df['year'], errors='raise')
|
||||
df['value'] = pd.to_numeric(df['value'], errors='raise')
|
||||
|
||||
# Validate ranges
|
||||
current_year = datetime.now().year
|
||||
if (df['year'] > current_year).any():
|
||||
raise ValueError(f"Future years found (max allowed: {current_year})")
|
||||
|
||||
if (df['value'] < 0).any():
|
||||
raise ValueError("Negative values found")
|
||||
|
||||
# Validate no duplicates
|
||||
if df.duplicated(subset=['year', 'commodity']).any():
|
||||
raise ValueError("Duplicate records found")
|
||||
|
||||
return df
|
||||
```
|
||||
|
||||
### Example: Docstrings
|
||||
|
||||
❌ **BAD**:
|
||||
```python
|
||||
def analyze(df, commodity):
|
||||
"""Analyze data"""
|
||||
# ...
|
||||
```
|
||||
|
||||
✅ **GOOD**:
|
||||
```python
|
||||
def analyze_yoy(
|
||||
df: pd.DataFrame,
|
||||
commodity: str,
|
||||
year1: int,
|
||||
year2: int
|
||||
) -> Dict[str, Any]:
|
||||
"""
|
||||
Perform year-over-year comparison analysis
|
||||
|
||||
Compares production, area, and yield between two years
|
||||
and decomposes growth into area vs yield contributions.
|
||||
|
||||
Args:
|
||||
df: DataFrame with columns ['year', 'commodity', 'production', 'area', 'yield']
|
||||
commodity: Commodity name (e.g., "CORN", "SOYBEANS")
|
||||
year1: Current year to compare
|
||||
year2: Previous year to compare against
|
||||
|
||||
Returns:
|
||||
Dict containing:
|
||||
- production_current (float): Production in year1 (million units)
|
||||
- production_previous (float): Production in year2
|
||||
- change_absolute (float): Absolute change
|
||||
- change_percent (float): Percent change
|
||||
- decomposition (dict): Area vs yield contribution
|
||||
- interpretation (str): "increase", "decrease", or "stable"
|
||||
|
||||
Raises:
|
||||
ValueError: If commodity not found in data
|
||||
ValueError: If either year not found in data
|
||||
DataQualityError: If production != area * yield (tolerance > 1%)
|
||||
|
||||
Example:
|
||||
>>> df = pd.DataFrame([
|
||||
... {'year': 2023, 'commodity': 'CORN', 'production': 15.3, 'area': 94.6, 'yield': 177},
|
||||
... {'year': 2022, 'commodity': 'CORN', 'production': 13.7, 'area': 89.2, 'yield': 173}
|
||||
... ])
|
||||
>>> result = analyze_yoy(df, "CORN", 2023, 2022)
|
||||
>>> result['change_percent']
|
||||
11.7
|
||||
"""
|
||||
# [Complete implementation]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Anti-Patterns
|
||||
|
||||
### Anti-Pattern 1: Partial Implementation
|
||||
|
||||
❌ **NO**:
|
||||
```python
|
||||
def yoy_comparison(df, commodity, year1, year2):
|
||||
# Implement YoY comparison
|
||||
pass
|
||||
|
||||
def state_ranking(df, commodity):
|
||||
# TODO: implement ranking
|
||||
raise NotImplementedError()
|
||||
```
|
||||
|
||||
✅ **YES**:
|
||||
```python
|
||||
# [Complete and functional code for BOTH functions]
|
||||
```
|
||||
|
||||
### Anti-Pattern 2: Empty References
|
||||
|
||||
❌ **NO**:
|
||||
```markdown
|
||||
# Analysis Methods
|
||||
|
||||
## YoY Comparison
|
||||
|
||||
This method compares two years.
|
||||
|
||||
## Ranking
|
||||
|
||||
This method ranks states.
|
||||
```
|
||||
|
||||
✅ **YES**:
|
||||
```markdown
|
||||
# Analysis Methods
|
||||
|
||||
## YoY Comparison
|
||||
|
||||
### Objective
|
||||
Compare metrics between current and previous year...
|
||||
|
||||
### Detailed Methodology
|
||||
|
||||
**Formulas**:
|
||||
```
|
||||
Δ X = X(t) - X(t-1)
|
||||
Δ X% = (Δ X / X(t-1)) × 100
|
||||
```
|
||||
|
||||
**Decomposition** (for production):
|
||||
[Complete mathematics]
|
||||
|
||||
**Interpretation**:
|
||||
- |Δ| < 2%: Stable
|
||||
- Δ > 10%: Significant increase
|
||||
[...]
|
||||
|
||||
### Validations
|
||||
[List]
|
||||
|
||||
### Complete Numerical Example
|
||||
[With real values]
|
||||
```
|
||||
|
||||
### Anti-Pattern 3: Useless Configs
|
||||
|
||||
❌ **NO**:
|
||||
```json
|
||||
{
|
||||
"api_url": "INSERT_URL",
|
||||
"api_key": "INSERT_KEY"
|
||||
}
|
||||
```
|
||||
|
||||
✅ **YES**:
|
||||
```json
|
||||
{
|
||||
"_comment": "Configuration for NASS USDA Agent",
|
||||
"api": {
|
||||
"base_url": "https://quickstats.nass.usda.gov/api",
|
||||
"_note": "This is the official USDA NASS API base URL",
|
||||
"api_key_env": "NASS_API_KEY",
|
||||
"_key_instructions": "Get free API key from: https://quickstats.nass.usda.gov/api#registration"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Final Validation
|
||||
|
||||
Before delivering to user, verify:
|
||||
|
||||
### Sanity Test
|
||||
|
||||
```bash
|
||||
# 1. Python syntax
|
||||
find scripts -name "*.py" -exec python -m py_compile {} \;
|
||||
|
||||
# 2. JSON syntax
|
||||
python -c "import json; json.load(open('assets/config.json'))"
|
||||
|
||||
# 3. Imports make sense
|
||||
grep -r "^import\|^from" scripts/*.py | sort | uniq
|
||||
# Verify all libs are: stdlib, requests, pandas, numpy
|
||||
# No imports of uninstalled libs
|
||||
|
||||
# 4. SKILL.md has frontmatter
|
||||
head -5 SKILL.md | grep "^---$"
|
||||
|
||||
# 5. SKILL.md size
|
||||
wc -w SKILL.md
|
||||
# Should be > 5000 words
|
||||
```
|
||||
|
||||
### Final Checklist
|
||||
|
||||
- [ ] Syntax check passed (Python, JSON)
|
||||
- [ ] No import of non-existent lib
|
||||
- [ ] No TODO or pass
|
||||
- [ ] SKILL.md > 5000 words
|
||||
- [ ] References with content
|
||||
- [ ] README with complete instructions
|
||||
- [ ] DECISIONS.md created
|
||||
- [ ] requirements.txt created
|
||||
Reference in New Issue
Block a user