| name | feedback |
| description | Use when implementation, review, security, scalability, or incident work reveals that an upstream .forge/ artifact is wrong, when a contract is missing an operation, when an ADR is being contradicted by a current need, when security recommends architecture changes, or when the user says "we discovered the spec is wrong". |
Feedback (reverse cascade)
Overview
Capture a finding from any downstream stage into a structured .forge/feedback/<timestamp>-<source>.md entry that targets one upstream artifact. The entry stays as status: PENDING until the upstream skill re-runs and addresses it. forge-sync flags the target artifact as FEEDBACK_PENDING until the entry is resolved.
This is the only sanctioned reverse-cascade primitive. The forward chain (prd → arch → tasks → code) flows one direction; backward propagation happens through these entries, not by directly editing upstream artifacts mid-stream.
When to Use
- During
/build you discover the relevant contract is missing an operation or has the wrong shape
- During
/review you find an architectural flaw that wasn't visible at design time
- During
/secure or /scale you produce a recommendation that implies architecture changes (add a WAF, change a data store, add a gateway)
- During an incident you discover an error path the error-handling spec didn't cover
- After a sprint, you realize ≥3 tasks split mid-flight — the plan needs an update before the next sprint
When NOT to Use
- The fix is fully contained inside the current stage (don't escalate every implementation detail)
- You have permission to edit the upstream artifact directly and want to do so — then just edit it;
forge-sync will flag downstream as STALE
- The finding is a question, not a recommended change — discuss with the user first; file the entry once a recommendation crystallizes
- The target artifact doesn't exist (
.forge/security.md not yet generated) — run the source skill instead
Common Rationalizations
| Thought | Reality |
|---|
| "I'll just edit the contract inline" | Then the chain has no record of WHY it changed. Future readers see a contract that contradicts the PRD with no explanation. |
| "Filing a feedback entry is overhead — I'll fix it later" | "Later" means the finding is forgotten by the time the upstream skill re-runs. The entry is the memory. |
| "The upstream skill will figure it out when it re-runs" | The upstream skill regenerates from its inputs, not from the downstream's discovery. Without a feedback entry, the regenerated artifact has the same flaw. |
| "This is too small for a feedback entry" | Three small findings ignored = one big surprise at /ship. |
| "I'll just tell the user verbally" | Verbal findings evaporate. The entry survives session boundaries. |
Red Flags
- Editing
.forge/contracts/<X>.md directly during /build instead of filing a feedback entry
- A sprint ends with no
.forge/feedback/ entries despite ≥3 tasks having notes populated
forge-sync reports FEEDBACK_PENDING on artifacts that are about to be re-generated, but the regenerating skill doesn't read .forge/feedback/- A
.forge/feedback/*.md file exists with status: PENDING for more than two sprints — either resolve it or mark it DEFERRED with a reason
Core Process
Step 1: Identify source, target, and finding
- Source stage: which skill or activity discovered the issue (
build, review, secure, scale, incident, manual)
- Source context: task ID, commit, PR, incident ID, or "manual" if ad-hoc
- Target artifact: which
.forge/ file needs revision. Must exist on disk. If multiple files need revision, file separate entries.
- Finding: what was discovered (1-3 sentences, specific)
- Recommended change: what should change in the target artifact (specific enough that re-running the source skill can apply it)
Step 2: Decide severity
Choose one:
- NEEDS_REVIEW — finding requires a human decision; auto-cascade not safe (e.g., "add WAF" — the human decides whether to absorb the change in architecture or defer)
- FEEDBACK_PENDING — recommended change is mechanical; the upstream skill can apply it on re-run (e.g., "add
refund endpoint to PaymentService contract")
Both states block /ship. Only NEEDS_REVIEW blocks /build if it touches the in-flight task's contract.
Step 3: Write the entry
Path: .forge/feedback/<ISO8601-UTC-with-dashes>-<source>.md — e.g., .forge/feedback/2026-05-14T103000Z-build.md.
<!-- forge:meta
generated_by: feedback
generated_at: 2026-05-14T10:30:00Z
depends_on: [.forge/contracts/payment-service.md]
generated_from:
.forge/contracts/payment-service.md: <target's content_hash AT filing time>
content_hash: <first 8 chars of sha256 over this entry's body>
-->
# Feedback: <short title>
- **Source stage:** build (incremental-implementation, task T-042)
- **Source context:** commit pending; branch task/T-042-refund-flow
- **Target artifact:** .forge/contracts/payment-service.md
- **Severity:** FEEDBACK_PENDING
- **Status:** PENDING
- **Filed at:** 2026-05-14T10:30:00Z
- **Resolved at:** —
## Finding
While implementing the refund flow, the PaymentService contract has no `refund(transactionId, amount)` operation. The PRD's "User can refund failed transactions within 30 days" story can't be satisfied without it.
## Recommended change
Add to `Provides` in `.forge/contracts/payment-service.md`:
refund(input: RefundInput): RefundOutput | RefundError
with:
- `RefundInput = { transactionId: string, amount?: number, idempotencyKey: string }`
- `RefundOutput = { refundId, refundedAt, amount }`
- `RefundError` cases: `TransactionNotFound`, `RefundWindowExpired`, `AlreadyRefunded`, `PartialRefundNotAllowed`
Idempotency-Key required per `api-design.md` mutation policy.
## Cascade
- Re-run `/architect` (or edit the contract directly) to address this entry.
- After contract update, re-run `/plan` if the refund story needs new tasks beyond T-042.
- `forge-sync` will mark this entry `RESOLVED` once the target artifact's `generated_at` advances past this entry's `generated_at` AND the recommended operation appears in the target.
depends_on is the target_artifact (single-element list) — that's what forge-sync reads to identify what's being annotated.
Step 4: Confirm with user
Print the entry path and a one-line summary:
Filed .forge/feedback/2026-05-14T103000Z-build.md — target .forge/contracts/payment-service.md, severity FEEDBACK_PENDING. Run /sync to see chain impact.
Do not modify the target artifact in this skill. The skill is write-only into .forge/feedback/.
Step 5: Tracking resolution
The feedback skill itself does not resolve entries. Resolution happens when the targeted upstream skill re-runs:
- The upstream skill (e.g.,
architecture-and-contracts) reads all .forge/feedback/*.md entries where target_artifact matches an output it owns AND status: PENDING.
- It addresses each in its regeneration.
- After writing, it updates each addressed entry:
status: RESOLVED, resolved_at: <now UTC>, resolved_by: <commit or "manual">.
forge-sync confirms the resolution by checking that the target artifact's content reflects the recommended change.
Entries can also be marked DEFERRED (with a reason in the body) when the team decides not to act — the entry stays in the directory as historical record.
Verification
